Codex

Authentication & API Keys

1 min read

Every request to the Codex API requires authentication. This guide covers how to generate credentials, obtain access tokens, and securely authenticate your API calls.

Generating API Keys

Navigate to your project settings and select the API Keys tab. Click Generate New Key to create a client ID and secret pair. Store the secret securely — it is only shown once at creation time.

Important: API keys inherit the permissions of the project they belong to. A key created in a read-only project cannot write data, regardless of the scopes requested.

Obtaining an Access Token

Exchange your client credentials for a short-lived access token using the token endpoint:

curl -X POST https://api.codex.dev/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id": "your_client_id", "client_secret": "your_secret"}'

A successful response returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Tokens expire after one hour. Your application should handle token refresh before expiration to avoid interrupted requests.

Using the Token

Include the access token in the Authorization header of every API request:

curl https://api.codex.dev/v1/documents \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

SDK Authentication

If you use the official SDK, authentication is handled automatically. Pass your API key at initialization:

const codex = require('@codex/sdk');

const client = new codex.Client({
  apiKey: process.env.CODEX_API_KEY,
  // Optional: set custom base URL
  baseUrl: 'https://api.codex.dev/v1'
});

// The SDK handles token refresh automatically
const docs = await client.documents.list();

Rate Limits

Authenticated requests are limited to 1,000 per minute per API key. If you exceed this limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

For bulk operations, use the batch endpoints which count as a single request regardless of the number of items processed.

Security Best Practices