Authentication

All External API requests require an API key. Keys are scoped to your user account and inherit your subscription limits, provider permissions, and rate limits.

Passing your API key

Use either header style:

X-API-Key: your-api-key-here

Authorization: Bearer your-api-key-here

Both are accepted on GET and POST /api/external/ai.

Creating and managing keys

1. Go to Dashboard → Settings → API Keys
2. Create a key with an optional name and restrictions
3. Optionally limit:
   • Allowed providers
   • Allowed models
   • Rate limit per hour
   • Max tokens per request
   • Expiration date

Revoke unused keys immediately from the same page.

Security best practices

• Never commit API keys to source control
• Prefer server-side usage over browser-side calls
• Rotate keys periodically and after any suspected leak
• Scope keys to the minimum providers and models you need
• Use separate keys for development and production

Missing or invalid key

{
  "success": false,
  "error": "API key is required. Please provide it in X-API-Key header or Authorization header."
}

HTTP status: 401 Unauthorized

Restricted key responses

If a key is valid but blocked by policy, the API returns details such as:

{
  "success": false,
  "error": "Provider not allowed for this API key",
  "details": {
    "isExpired": false,
    "isProviderAllowed": false,
    "isModelAllowed": true,
    "isRateLimited": false,
    "remainingHourlyRequests": 42
  }
}

Typical statuses:

Condition	Status
Expired key	401
Rate limited	429
Provider/model not allowed	403
Invalid key	401

Next: API Overview