API Key Management

Overview

The API Key Management API allows you to create, list, update, delete, and regenerate API keys for authenticating proxy requests. API keys support model restrictions, usage limits (token-based and cost-based), and expiration dates.

All API Key Management endpoints require dashboard authentication via session cookie.

Create API Key

POST /api/api-keys

endpoint

Create a new API key with optional restrictions and limits.

Request Body

name

string

required

Human-readable name for the API key (1-128 characters)

allowed_models

array

List of allowed model names. If null or empty, all models are allowed.

expires_at

string

ISO 8601 timestamp when the key should expire. If null, the key never expires.

limits

array

Array of usage limit rules

Show LimitRule object

limit_type

string

required

Type of limit: total_tokens, input_tokens, output_tokens, or cost_usd

limit_window

string

required

Time window: daily, weekly, or monthly

max_value

integer

required

Maximum value for the limit (must be >= 1)

model_filter

string

Optional model name to scope this limit to a specific model. If null, limit applies globally.

weekly_token_limit

integer

deprecated

Legacy field for weekly token limit. Use limits array instead.

Response

string

required

Unique key identifier (UUID)

name

string

required

Key name

key

string

required

The full API key (format: sk-clb-{48 hex chars}). Only returned once on creation.

key_prefix

string

required

First 16 characters of the key for identification

allowed_models

array

List of allowed models, or null for all models

expires_at

string

Expiration timestamp

is_active

boolean

required

Whether the key is active

created_at

string

required

Creation timestamp

last_used_at

string

Last usage timestamp

limits

array

required

Array of limit rules with current usage

Show LimitRuleResponse

integer

Limit rule ID

limit_type

string

Limit type

limit_window

string

Time window

max_value

integer

Maximum value

current_value

integer

Current usage

model_filter

string

Optional model filter

reset_at

string

Next reset timestamp

Example Request

curl -X POST "https://your-instance.com/api/api-keys" \
  -H "Cookie: dashboard_session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "allowed_models": ["claude-opus-4-20250514", "claude-sonnet-4-20250514"],
    "expires_at": "2026-12-31T23:59:59Z",
    "limits": [
      {
        "limit_type": "total_tokens",
        "limit_window": "daily",
        "max_value": 1000000
      },
      {
        "limit_type": "cost_usd",
        "limit_window": "monthly",
        "max_value": 100,
        "model_filter": "claude-opus-4-20250514"
      }
    ]
  }'

Example Response

{
  "id": "key_abc123def456",
  "name": "Production Key",
  "key": "sk-clb-a1b2c3d4e5f6789012345678901234567890123456789012",
  "key_prefix": "sk-clb-a1b2c3d4",
  "allowed_models": ["claude-opus-4-20250514", "claude-sonnet-4-20250514"],
  "expires_at": "2026-12-31T23:59:59Z",
  "is_active": true,
  "created_at": "2026-03-03T19:00:00Z",
  "last_used_at": null,
  "limits": [
    {
      "id": 1,
      "limit_type": "total_tokens",
      "limit_window": "daily",
      "max_value": 1000000,
      "current_value": 0,
      "model_filter": null,
      "reset_at": "2026-03-04T00:00:00Z"
    },
    {
      "id": 2,
      "limit_type": "cost_usd",
      "limit_window": "monthly",
      "max_value": 100,
      "current_value": 0,
      "model_filter": "claude-opus-4-20250514",
      "reset_at": "2026-04-01T00:00:00Z"
    }
  ]
}

The full API key is only returned once during creation. Store it securely - it cannot be retrieved later.

Error Responses

400

error

invalid_api_key_payload: Invalid request payload (e.g., invalid limit configuration)

List API Keys

GET /api/api-keys

endpoint

Retrieve all API keys with their metadata and current usage.

Response

Returns an array of API key objects (same structure as create response, but without the key field).

Example Request

curl -X GET "https://your-instance.com/api/api-keys" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

[
  {
    "id": "key_abc123def456",
    "name": "Production Key",
    "key_prefix": "sk-clb-a1b2c3d4",
    "allowed_models": ["claude-opus-4-20250514"],
    "expires_at": "2026-12-31T23:59:59Z",
    "is_active": true,
    "created_at": "2026-03-03T19:00:00Z",
    "last_used_at": "2026-03-03T20:15:00Z",
    "limits": [
      {
        "id": 1,
        "limit_type": "total_tokens",
        "limit_window": "daily",
        "max_value": 1000000,
        "current_value": 45230,
        "model_filter": null,
        "reset_at": "2026-03-04T00:00:00Z"
      }
    ]
  }
]

Update API Key

PATCH /api/api-keys/{key_id}

endpoint

Update an existing API key’s properties. Only provided fields are updated.

Path Parameters

key_id

string

required

The API key ID to update

Request Body

name

string

New name for the key (1-128 characters)

allowed_models

array

Updated list of allowed models

expires_at

string

New expiration timestamp

is_active

boolean

Set to false to deactivate the key

limits

array

Updated limit rules. If omitted, existing limits are preserved. See create endpoint for structure.

reset_usage

boolean

Set to true to reset all usage counters to zero

Response

Returns the updated API key object (same structure as list endpoint).

Example Request - Deactivate Key

curl -X PATCH "https://your-instance.com/api/api-keys/key_abc123def456" \
  -H "Cookie: dashboard_session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Example Request - Update Limits

curl -X PATCH "https://your-instance.com/api/api-keys/key_abc123def456" \
  -H "Cookie: dashboard_session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "limits": [
      {
        "limit_type": "total_tokens",
        "limit_window": "weekly",
        "max_value": 5000000
      }
    ]
  }'

When updating limits, existing usage state is preserved for matching rules (same type, window, and model_filter). Only the max_value can be changed without resetting usage.

Error Responses

404

error

Not Found: The specified key ID does not exist

400

error

invalid_api_key_payload: Invalid request payload

Delete API Key

DELETE /api/api-keys/{key_id}

endpoint

Permanently delete an API key. The key will immediately stop authenticating.

Path Parameters

key_id

string

required

The API key ID to delete

Response

Returns HTTP 204 No Content on success.

Example Request

curl -X DELETE "https://your-instance.com/api/api-keys/key_abc123def456" \
  -H "Cookie: dashboard_session=your-session-token"

Error Responses

404

error

Not Found: The specified key ID does not exist

Regenerate API Key

POST /api/api-keys/{key_id}/regenerate

endpoint

Generate a new key value while preserving all other properties. The old key immediately stops working.

Path Parameters

key_id

string

required

The API key ID to regenerate

Response

Returns the updated API key object with the new key and key_prefix. The full key is only shown once.

Example Request

curl -X POST "https://your-instance.com/api/api-keys/key_abc123def456/regenerate" \
  -H "Cookie: dashboard_session=your-session-token"

Example Response

{
  "id": "key_abc123def456",
  "name": "Production Key",
  "key": "sk-clb-9f8e7d6c5b4a3210987654321098765432109876543210",
  "key_prefix": "sk-clb-9f8e7d6c",
  "allowed_models": ["claude-opus-4-20250514"],
  "expires_at": "2026-12-31T23:59:59Z",
  "is_active": true,
  "created_at": "2026-03-03T19:00:00Z",
  "last_used_at": "2026-03-03T20:15:00Z",
  "limits": []
}

The old key stops working immediately. Update all clients with the new key value.

Error Responses

404

error

Not Found: The specified key ID does not exist

Key Format

All API keys follow the format:

sk-clb-{48 hexadecimal characters}

Example: sk-clb-a1b2c3d4e5f6789012345678901234567890123456789012 The system stores only the SHA256 hash of the key. The plain key is returned only during creation and regeneration.

Usage Limits

Limit Types

total_tokens: Total input + output tokens
input_tokens: Input tokens only
output_tokens: Output tokens only
cost_usd: Cost in US dollars

Limit Windows

daily: Resets every 24 hours
weekly: Resets every 7 days
monthly: Resets on the 1st of each month

Model-Scoped Limits

Limits can be scoped to specific models using the model_filter field:

model_filter: null - Applies to all requests (global limit)
model_filter: "claude-opus-4-20250514" - Applies only to requests using this model

Multiple limits can be combined. For example:

[
  {
    "limit_type": "total_tokens",
    "limit_window": "daily",
    "max_value": 1000000,
    "model_filter": null
  },
  {
    "limit_type": "cost_usd",
    "limit_window": "monthly",
    "max_value": 50,
    "model_filter": "claude-opus-4-20250514"
  }
]

This configuration:

Limits total daily tokens across all models to 1M
Limits monthly cost for Opus requests to $50

Limit Enforcement

When a limit is exceeded, proxy requests return:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API key rate limit exceeded",
    "type": "rate_limit_error"
  }
}

HTTP Status: 429 Too Many Requests

Authentication

All API key management endpoints require dashboard authentication via session cookie. These endpoints are separate from the API key authentication used for proxy requests.

Common Error Codes

Code	Description
`invalid_api_key_payload`	Request payload validation failed
`rate_limit_exceeded`	API key usage limit exceeded (during proxy requests)
`model_not_allowed`	Requested model not in allowed_models list (during proxy requests)

Overview

OpenAI-Compatible Endpoints

Codex Endpoints

Management API

​Overview

​Create API Key

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

​List API Keys

​Response

​Example Request

​Example Response

​Update API Key

​Path Parameters

​Request Body

​Response

​Example Request - Deactivate Key

​Example Request - Update Limits

​Error Responses

​Delete API Key

​Path Parameters

​Response

​Example Request

​Error Responses

​Regenerate API Key

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Key Format

​Usage Limits

​Limit Types

​Limit Windows

​Model-Scoped Limits

​Limit Enforcement

​Authentication

​Common Error Codes

Build docs developers (and LLMs) love

Overview

Create API Key

Request Body

Response

Example Request

Example Response

Error Responses

List API Keys

Response

Example Request

Example Response

Update API Key

Path Parameters

Request Body

Response

Example Request - Deactivate Key

Example Request - Update Limits

Error Responses

Delete API Key

Path Parameters

Response

Example Request

Error Responses

Regenerate API Key

Path Parameters

Response

Example Request

Example Response

Error Responses

Key Format

Usage Limits

Limit Types

Limit Windows

Model-Scoped Limits

Limit Enforcement

Authentication

Common Error Codes