Overview

API keys provide Bearer token authentication for the CLI, MCP server, and external integrations. Keys are SHA-256 hashed before storage, so the raw key is only available at creation time.

List keys

Retrieves all API keys for the authenticated user.

GET /api/keys

Response

[
  {
    "id": "key_abc123",
    "name": "CLI - Development",
    "prefix": "contox_sk_abc1...",
    "lastUsed": "2025-01-20T14:00:00Z",
    "createdAt": "2025-01-15T10:30:00Z"
  }
]

Note that the full key value is never returned after creation. Only the prefix is shown for identification purposes.

Create key

Creates a new API key.

POST /api/keys

Request body

Example

curl -X POST https://contox.dev/api/keys \
  -H "Authorization: Bearer contox_sk_existingkey" \
  -H "Content-Type: application/json" \
  -d '{"name": "CLI - Production"}'

Response

{
  "id": "key_def456",
  "name": "CLI - Production",
  "key": "contox_sk_full_raw_key_shown_only_once",
  "createdAt": "2025-01-20T14:00:00Z"
}

The key field contains the full raw API key. Copy it immediately -- it will never be shown again.

Delete key

Permanently revokes an API key.

DELETE /api/keys

Request body

Example

curl -X DELETE https://contox.dev/api/keys \
  -H "Authorization: Bearer contox_sk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"keyId": "key_abc123"}'

Response

Returns 204 No Content on success.

Security

• Keys are SHA-256 hashed before storage -- Contox cannot retrieve your raw key
• Keys follow the format contox_sk_<random>
• The raw key is shown exactly once at creation time
• Deleted keys are immediately invalidated
• Each key tracks its last usage timestamp

Best practices

• Use descriptive names like "CLI - Production" or "MCP Server - My Laptop"
• Create separate keys for different environments and tools
• Rotate keys periodically by creating a new key and deleting the old one
• Store keys securely in environment variables or a secrets manager
• Delete unused keys to minimize the attack surface
• Never commit keys to version control

Next steps

• Authentication -- Overview of all authentication methods
• Dashboard API Keys -- Manage keys in the UI