API Keys

Key Format

API keys follow the format sk_live_{random} where {random} is a cryptographically random string. Keys are hashed with bcrypt before storage — the full key is only shown once at creation time.

Create a Key

curl -X POST https://cavos.org/api/keys \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Production Key",
    "creditLimit": 100
  }'

Response (201):

{
  "message": "API key created successfully",
  "apiKey": {
    "id": "key-uuid",
    "name": "My Production Key",
    "keyPrefix": "sk_live_abc1...",
    "creditLimit": 100,
    "creditsUsed": 0,
    "status": "ACTIVE",
    "createdAt": "2024-01-01T00:00:00Z"
  },
  "key": "sk_live_abc123def456..."
}

Caution

Save the key value immediately — it is only shown once and cannot be retrieved later.

Validation Rules

Rule	Constraint
Name	Required, non-empty
Credit limit	1–10,000 (default: 50)
Max keys per user	20
Key format	sk_live_{random}

List Keys

curl https://cavos.org/api/keys \
  -H "Authorization: Bearer <session_token>"

Returns all non-deleted keys with prefix, usage, and status. Full key values are never returned after creation.

Key Status

Status	Description
ACTIVE	Key is usable
REVOKED	Key has been disabled

Soft Deletion

Deleted keys are soft-deleted (marked with deletedAt timestamp) and excluded from listing. They can no longer authenticate requests.