API Authentication

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

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:

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

Previous: Workflows | Next: Studio API