Managing API Keys

API keys provide secure authentication for applications and services accessing your Codex-LB instance. Each API key can have custom limits, model restrictions, and expiration dates.

Creating an API Key

Navigate to API Keys

In the Codex-LB dashboard, go to the API Keys section.

Configure Key Settings

Click “Create API Key” and configure:Basic Settings

Name: A descriptive name for the key (e.g., “Production App”, “Development”, “QA Testing”)
Allowed Models: Optional list of models this key can access (leave empty for all models)
Expiration: Optional expiration date for automatic key rotation

Rate Limits (Optional)See Rate Limiting for detailed configuration options.

Copy the API Key

After creation, the full API key will be displayed once. Copy and store it securely.

sk-clb-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789

This is the only time the full key will be shown. If you lose it, you’ll need to regenerate the key.

Use the API Key

Include the API key in your requests using the Authorization header:

curl https://your-codex-lb-instance.com/v1/chat/completions \
  -H "Authorization: Bearer sk-clb-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

API Key Properties

Name

A human-readable identifier for the key. Use descriptive names to easily identify keys:

production-web-app
mobile-app-ios
staging-environment
team-dev-testing

Key Format

All Codex-LB API keys follow the format:

sk-clb-{32-character-token}

Prefix: sk-clb- identifies the key as a Codex-LB API key
Token: 32-character URL-safe random string
Storage: Keys are hashed using SHA-256 before storage

Key Prefix

The dashboard displays only the first 15 characters of each key for identification:

sk-clb-AbCdEfG...

This allows you to identify keys without exposing the full token.

Allowed Models

Restrict which models an API key can access:

{
  "name": "Limited Key",
  "allowed_models": ["gpt-4", "gpt-4-turbo", "o1-preview"]
}

Leave empty or null to allow all models
Requests for non-allowed models will return 403 Forbidden
Model names must match exactly (case-sensitive)

Expiration

Set an expiration date for automatic key rotation:

{
  "name": "Temporary Key",
  "expires_at": "2026-12-31T23:59:59Z"
}

Expired keys return 401 Unauthorized
Set to null for keys that never expire
Use expiration for temporary access or security policies requiring rotation

Active Status

Keys can be enabled or disabled:

Active (is_active: true): Key can authenticate requests
Inactive (is_active: false): Key is disabled and returns 401 Unauthorized

Use this for temporary suspension without deleting the key.

Managing Existing Keys

Viewing API Keys

The API keys list shows:

Key name
Key prefix (first 15 characters)
Active status
Allowed models (if configured)
Expiration date (if set)
Created date
Last used timestamp
Current usage for each limit

Updating an API Key

You can update most key properties:

Select the Key

Click on the key you want to modify in the API Keys list.

Edit Properties

Modify any of the following:

Name
Allowed models
Expiration date
Active status
Rate limits (add, remove, or modify)

Save Changes

Click “Save” to apply changes. The key itself (token) remains unchanged.

Note: You cannot change the actual key token. To change the token, you must regenerate the key.

Regenerating an API Key

Regenerate a key to create a new token while keeping the same configuration:

Select the Key

Navigate to the key you want to regenerate.

Regenerate

Click “Regenerate” and confirm the action.

The old key will stop working immediately. Update all applications using the old key.

Copy New Key

Copy the new API key and update your applications.The key configuration (name, limits, expiration) remains the same, but a new token is generated.

Deactivating an API Key

Temporarily disable a key without deleting it:

{
  "is_active": false
}

Use cases:

Investigating suspicious activity
Temporarily revoking access
Compliance requirements
Testing fallback behavior

Reactivate by setting is_active: true.

Deleting an API Key

Permanently remove an API key:

Select the Key

Navigate to the key you want to delete.

Delete

Click “Delete” and confirm the action.

This action is permanent and cannot be undone. The key will immediately stop working.

Update Applications

Update any applications using the deleted key with a new API key.

Rate Limits

API keys support granular rate limiting. See the Rate Limiting guide for detailed information.

Limit Types

Total Tokens: Combined input and output tokens
Input Tokens: Prompt tokens only
Output Tokens: Completion tokens only
Cost (USD): Total cost in microdollars

Limit Windows

Daily: Resets every 24 hours
Weekly: Resets every 7 days
Monthly: Resets every 30 days

Model-Specific Limits

Apply different limits for different models:

{
  "limits": [
    {
      "limit_type": "cost_usd",
      "limit_window": "daily",
      "max_value": 10000000,
      "model_filter": "gpt-4"
    },
    {
      "limit_type": "cost_usd",
      "limit_window": "daily",
      "max_value": 5000000,
      "model_filter": "gpt-4-turbo"
    }
  ]
}

Usage Tracking

Real-Time Usage

Each API key displays current usage for all configured limits:

{
  "limits": [
    {
      "limit_type": "total_tokens",
      "limit_window": "daily",
      "max_value": 1000000,
      "current_value": 245680,
      "reset_at": "2026-03-04T00:00:00Z"
    }
  ]
}

Last Used Timestamp

Track when each key was last used:

last_used_at: Timestamp of the most recent successful request
Updated asynchronously after request completion
Useful for identifying unused keys

Resetting Usage

Manually reset usage counters:

{
  "reset_usage": true
}

This sets all current_value fields to 0 and updates reset_at timestamps.

Authentication Flow

When a request arrives with an API key:

Extract Key

Codex-LB extracts the API key from the Authorization: Bearer {key} header.

Validate Key

The key is hashed and looked up in the database:

Check if key exists
Check if key is active (is_active: true)
Check if key has expired (expires_at > now)
Check if requested model is allowed

Check Rate Limits

For each configured limit:

Check if limit applies to the requested model
Check if current usage is below max value
Reserve usage quota for the request
Update last_used_at timestamp

Process Request

If all checks pass, the request is forwarded to the upstream ChatGPT API.After the request completes, actual token usage is calculated and limits are updated.

Error Responses

Invalid API Key

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

HTTP Status: 401 Unauthorized Causes:

Key doesn’t exist
Key is inactive
Key has expired
Invalid key format

Model Not Allowed

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

HTTP Status: 403 Forbidden Cause: Requested model not in allowed_models list.

Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API key total_tokens daily limit exceeded",
    "type": "rate_limit_error",
    "reset_at": "2026-03-04T00:00:00Z"
  }
}

HTTP Status: 429 Too Many Requests Headers:

X-RateLimit-Limit-Total-Tokens-Daily: 1000000
X-RateLimit-Remaining-Total-Tokens-Daily: 0
X-RateLimit-Reset-Total-Tokens-Daily: 1709539200

See Rate Limiting for more details.

Security Best Practices

Treat API keys like passwords. Never commit them to source control or share them publicly.

Key Management

Rotate keys regularly: Set expiration dates and rotate before they expire
Use environment variables: Store keys in environment variables, not in code
Separate keys per environment: Use different keys for dev, staging, and production
Monitor usage: Review last_used_at to identify unused or compromised keys
Revoke compromised keys: Immediately delete or deactivate any exposed keys

Access Control

Principle of least privilege: Grant minimum necessary access (models, limits)
Model restrictions: Limit expensive models to production keys only
Rate limits: Set appropriate limits based on expected usage
Expiration dates: Use temporary keys for contractors or testing

Monitoring

Review API key usage regularly
Set up alerts for unusual activity
Track rate limit violations
Monitor last used timestamps for stale keys

API Reference

For programmatic API key management:

Next Steps

Rate Limiting

Configure detailed rate limits for your API keys

Model Routing

Control how requests are routed to ChatGPT accounts

​Creating an API Key

​API Key Properties

​Name

​Key Format

​Key Prefix

​Allowed Models

​Expiration

​Active Status

​Managing Existing Keys

​Viewing API Keys

​Updating an API Key

​Regenerating an API Key

​Deactivating an API Key

​Deleting an API Key

​Rate Limits

​Limit Types

​Limit Windows

​Model-Specific Limits

​Usage Tracking

​Real-Time Usage

​Last Used Timestamp

​Resetting Usage

​Authentication Flow

​Error Responses

​Invalid API Key

​Model Not Allowed

​Rate Limit Exceeded

​Security Best Practices

​Key Management

​Access Control

​Monitoring

​API Reference

​Next Steps

Rate Limiting

Model Routing

Creating an API Key

API Key Properties

Name

Key Format

Key Prefix

Allowed Models

Expiration

Active Status

Managing Existing Keys

Viewing API Keys

Updating an API Key

Regenerating an API Key

Deactivating an API Key

Deleting an API Key

Rate Limits

Limit Types

Limit Windows

Model-Specific Limits

Usage Tracking

Real-Time Usage

Last Used Timestamp

Resetting Usage

Authentication Flow

Error Responses

Invalid API Key

Model Not Allowed

Rate Limit Exceeded

Security Best Practices

Key Management

Access Control

Monitoring

API Reference

Next Steps