API Authentication

Access note: Public self-serve API key generation is not available on girardai.com while the product app is in private beta. Use this page as the target auth model for pilots. Request keys through Contact Sales.

All Girard API requests require authentication. This guide covers how to obtain, use, and manage your API keys once your workspace is provisioned.

Overview

Girard uses API keys for authentication:

• Bearer Token - Include in Authorization header
• Organization Scoped - Keys belong to organizations
• Permission Based - Keys inherit organization permissions

Obtaining an API Key

Generate a New Key

1. Navigate to Settings > API Keys
2. Click Generate New Key
3. Enter a descriptive name (e.g., "Production App")
4. Optionally set an expiration date
5. Click Create
6. Copy the key immediately - it won't be shown again

API Key Format

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• sk_ - Prefix indicating secret key
• live_ - Environment (live or test)
• xxxx... - Unique identifier

Using Your API Key

HTTP Header Authentication

Include your API key in the Authorization header:

curl -X GET https://www.girardai.com/api/v1/workflows \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Request Examples

cURL

curl -X POST https://www.girardai.com/api/v1/workflows/{id}/execute \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"prompt": "Hello, world!"}}'

JavaScript (fetch)

const response = await fetch('https://www.girardai.com/api/v1/workflows', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

JavaScript (axios)

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://www.girardai.com/api/v1',
  headers: {
    'Authorization': 'Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  },
});

const response = await client.get('/workflows');

Python (requests)

import requests

headers = {
    'Authorization': 'Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://www.girardai.com/api/v1/workflows',
    headers=headers
)

data = response.json()

Python (httpx)

import httpx

async with httpx.AsyncClient() as client:
    response = await client.get(
        'https://www.girardai.com/api/v1/workflows',
        headers={
            'Authorization': 'Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        }
    )
    data = response.json()

Environment Variables

Store your API key securely in environment variables:

Setting Environment Variables

Linux/macOS:

export GIRARDAI_API_KEY="sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Windows (PowerShell):

$env:GIRARDAI_API_KEY = "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Windows (CMD):

set GIRARDAI_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Using in Code

// Node.js
const apiKey = process.env.GIRARDAI_API_KEY;

// With dotenv
require('dotenv').config();
const apiKey = process.env.GIRARDAI_API_KEY;

# Python
import os
api_key = os.environ.get('GIRARDAI_API_KEY')

.env File

Create a .env file (never commit to git):

GIRARDAI_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Add to .gitignore:

.env
.env.local
.env*.local

Error Responses

401 Unauthorized

API key is missing or invalid:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Common Causes:

• Missing Authorization header
• Malformed API key
• Expired API key
• Revoked API key

403 Forbidden

API key lacks required permissions:

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have permission for this resource"
  }
}

Common Causes:

• Key doesn't have access to requested resource
• Organization plan doesn't include feature
• Rate limit exceeded

API Key Management

Viewing Keys

1. Go to Settings > API Keys
2. See list of all keys
3. View:
   • Key name
   • Created date
   • Last used
   • Status

Revoking Keys

Immediately invalidate a compromised key:

1. Find the key in your list
2. Click Revoke
3. Confirm the action
4. Key is immediately invalid

Key Rotation

Best practice is to rotate keys periodically:

1. Generate a new key
2. Update your applications
3. Verify the new key works
4. Revoke the old key

Key Expiration

Set automatic expiration:

1. When creating a key, set expiration date
2. Key automatically becomes invalid after date
3. Receive notification before expiration

Rate Limiting

API requests are rate limited based on your plan:

Plan	Requests/Minute	Requests/Day
Free	60	1,000
Pro	300	10,000
Team	600	50,000
Enterprise	Custom	Custom

Rate Limit Headers

Check rate limit status in response headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1642694400

Rate Limit Exceeded

When rate limited, you'll receive:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}

Response Status: 429 Too Many Requests

Handling Rate Limits

async function makeRequest(url, options, retries = 3) {
  const response = await fetch(url, options);

  if (response.status === 429 && retries > 0) {
    const retryAfter = response.headers.get('Retry-After') || 60;
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return makeRequest(url, options, retries - 1);
  }

  return response;
}

Security Best Practices

DO

• ✅ Store keys in environment variables
• ✅ Use separate keys for dev/staging/production
• ✅ Rotate keys regularly
• ✅ Set expiration dates
• ✅ Monitor key usage
• ✅ Revoke unused keys

DON'T

• ❌ Commit keys to version control
• ❌ Share keys in plain text
• ❌ Use the same key everywhere
• ❌ Log API keys
• ❌ Include keys in client-side code
• ❌ Share keys between team members

If a Key is Compromised

1. Immediately revoke the compromised key
2. Generate a new key
3. Update all applications using the old key
4. Audit recent API usage for suspicious activity
5. Review how the key was exposed
6. Implement measures to prevent future exposure

Testing Authentication

Verify Key is Valid

curl -X GET https://www.girardai.com/api/v1/health \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Success Response:

{
  "status": "ok",
  "organization": "your-org-name",
  "plan": "pro"
}

Common Issues

Issue	Solution
"Invalid API key"	Check key is copied correctly
"Key expired"	Generate a new key
"Key revoked"	Generate a new key
"Missing header"	Ensure Authorization header is set
"Malformed header"	Check "Bearer " prefix is included

---

Previous: Workflows | Next: Studio API