API Key Management

API keys authenticate your requests to GateFlow. This guide covers creating, managing, and securing your keys.

Key Types

Production Keys (gw_prod_)

Use for live applications:

• Full access to all configured providers
• Requests logged for analytics
• Rate limits enforced
• Cost tracking enabled

Development Keys (gw_dev_)

Use for testing and development:

• Same capabilities as production
• Separate rate limits
• Clearly labeled in analytics
• Can be quickly rotated without affecting production

Creating API Keys

Via Dashboard

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Configure the key:
   • Name: Descriptive name (e.g., "Backend Production")
   • Type: Production or Development
   • Permissions: Optional restrictions
4. Click Create
5. Copy the key immediately - it won't be shown again

Via API

curl -X POST https://api.gateflow.ai/v1/management/api-keys \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Production",
    "type": "production",
    "permissions": {
      "models": ["gpt-4o", "claude-3-5-sonnet"],
      "rate_limit_rpm": 1000
    }
  }'

Response:

{
  "id": "key_abc123",
  "name": "Backend Production",
  "key": "gw_prod_abc123def456...",
  "type": "production",
  "created_at": "2024-01-15T10:30:00Z"
}

WARNING

The key field is only returned once at creation time. Store it securely.

Key Permissions

Restrict what a key can do:

Model Restrictions

Limit which models a key can access:

{
  "permissions": {
    "models": ["gpt-4o", "gpt-4o-mini"]
  }
}

Requests for other models return 403 Forbidden.

Rate Limits

Set per-key rate limits:

{
  "permissions": {
    "rate_limit_rpm": 100,      // Requests per minute
    "rate_limit_rpd": 10000     // Requests per day
  }
}

Cost Limits

Cap spending per key:

{
  "permissions": {
    "cost_limit_daily": 100.00,   // USD per day
    "cost_limit_monthly": 2000.00 // USD per month
  }
}

When limits are hit, requests return 429 Too Many Requests.

IP Restrictions

Restrict to specific IP addresses:

{
  "permissions": {
    "allowed_ips": [
      "203.0.113.0/24",
      "198.51.100.42"
    ]
  }
}

Using API Keys

In Headers (Recommended)

curl https://api.gateflow.ai/v1/chat/completions \
  -H "Authorization: Bearer gw_prod_your_key"

With OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_your_key"
)

With Environment Variables

export GATEFLOW_API_KEY="gw_prod_your_key"

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key=os.environ["GATEFLOW_API_KEY"]
)

Managing Keys

List Keys

curl https://api.gateflow.ai/v1/management/api-keys \
  -H "Authorization: Bearer gw_prod_admin_key"

Revoke a Key

curl -X DELETE https://api.gateflow.ai/v1/management/api-keys/key_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key"

Revoked keys immediately stop working. Active requests may fail.

Update Permissions

curl -X PATCH https://api.gateflow.ai/v1/management/api-keys/key_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "rate_limit_rpm": 2000
    }
  }'

Security Best Practices

1. Use Environment Variables

Never hardcode keys in source code:

# Bad
api_key = "gw_prod_abc123..."

# Good
api_key = os.environ["GATEFLOW_API_KEY"]

2. Separate Keys by Environment

Environment	Key Type	Key Name
Local dev	Development	"Local Dev"
CI/CD	Development	"CI Pipeline"
Staging	Production	"Staging Backend"
Production	Production	"Production Backend"

3. Apply Least Privilege

Only grant permissions that are needed:

{
  "permissions": {
    "models": ["gpt-4o-mini"],  // Only this model
    "rate_limit_rpm": 100,       // Conservative limit
    "cost_limit_daily": 50.00    // Budget cap
  }
}

4. Rotate Regularly

Set up key rotation for production keys.

5. Monitor Usage

Review key usage in the dashboard:

• Unexpected models being used
• Unusual request patterns
• Approaching rate/cost limits

Troubleshooting

"Invalid API Key" Error

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Causes:

• Key doesn't exist
• Key was revoked
• Typo in key

"Rate Limit Exceeded" Error

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Solutions:

• Wait and retry with backoff
• Increase key's rate limit
• Distribute across multiple keys

"Model Not Allowed" Error

{
  "error": {
    "message": "Model 'gpt-4o' not allowed for this API key",
    "type": "permission_error",
    "code": "model_not_allowed"
  }
}

Solutions:

• Update key permissions to include the model
• Use a different key with broader permissions

Next Steps

• Key Rotation - Automated key rotation
• Organizations & RBAC - Team management