Authentication

API Keys

Every request to the Universal AI API must include a valid API key. Keys are passed via the standard Authorization header using the Bearer scheme.

Creating an API Key

Create a new API key by sending a POST request to the admin endpoint:

curl -X POST https://api.universal-ai.dev/v1/admin/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-app"
  }'

Response:

{
  "id": "key_abc123",
  "name": "production-app",
  "key": "uai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2025-01-15T10:30:00Z"
}

Save the key value immediately. For security, the full key is only returned once at creation time.

Using Your API Key

Include your API key in the Authorization header of every request:

curl https://api.universal-ai.dev/v1/chat/completions \
  -H "Authorization: Bearer uai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

When using an OpenAI-compatible SDK, pass the key as the api_key parameter:

from openai import OpenAI

client = OpenAI(
    api_key="uai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.universal-ai.dev/v1"
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "uai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  baseURL: "https://api.universal-ai.dev/v1",
});

Listing API Keys

Retrieve all keys associated with your account:

curl https://api.universal-ai.dev/v1/admin/keys \
  -H "Authorization: Bearer uai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Revoking an API Key

Delete a key by its ID:

curl -X DELETE https://api.universal-ai.dev/v1/admin/keys/key_abc123 \
  -H "Authorization: Bearer uai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Revoked keys are rejected immediately on all subsequent requests.

Rate Limiting

Requests are rate-limited per API key. Rate limit information is returned in the response headers of every request:

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 12 seconds.",
    "retry_after": 12
  }
}

Default Limits

Best Practices

• Use exponential backoff when receiving 429 responses. Wait for the duration specified in retry_after before retrying.
• Cache responses on your end for repeated identical requests, or rely on the built-in caching layer.
• Distribute load across multiple API keys if you need higher throughput for different services.
• Keep keys secret. Never expose API keys in client-side code, public repositories, or browser requests. Always call the API from your backend.

Error Responses

Authentication errors return a 401 Unauthorized status:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided."
  }
}

Common causes:

• Missing Authorization header
• Malformed header (must be Bearer <key>)
• Revoked or expired API key
• Incorrect key value