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

endpoint

Create a new API key with optional restrictions and limits.

Request Body

string

required

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

array

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

string

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

array

Array of usage limit rules

Show LimitRule object

string

required

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

string

required

Time window: daily, weekly, or monthly

integer

required

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

string

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

integer

deprecated

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

Response

string

required

Unique key identifier (UUID)

string

required

Key name

string

required

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

string

required

First 16 characters of the key for identification

array

List of allowed models, or null for all models

string

Expiration timestamp

boolean

required

Whether the key is active

string

required

Creation timestamp

string

Last usage timestamp

array

required

Array of limit rules with current usage

Show LimitRuleResponse

integer

Limit rule ID

string

Limit type

string

Time window

integer

Maximum value

integer

Current usage

string

Optional model filter

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

error

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

List 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

endpoint

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

Path Parameters

string

required

The API key ID to update

Request Body

string

New name for the key (1-128 characters)

array

Updated list of allowed models

string

New expiration timestamp

boolean

Set to false to deactivate the key

array

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

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

error

Not Found: The specified key ID does not exist

error

invalid_api_key_payload: Invalid request payload

Delete API Key

endpoint

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

Path Parameters

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

error

Not Found: The specified key ID does not exist

Regenerate API Key

endpoint

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

Path Parameters

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

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

​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

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