API Key Endpoints

The API key endpoints manage the full lifecycle of programmatic access keys, including creation, validation, scoping, rotation, and revocation. Served by ApiKeyController at /api/v1/api-keys.

Endpoints

POST /api/v1/api-keys

Creates a new API key. The full key value is returned only once at creation time.

{
  "name": "CI Pipeline Key",
  "description": "Used by CI/CD pipeline for deployments",
  "scopes": ["queries:read", "queries:execute"],
  "keyType": "service",
  "testMode": false,
  "expirationDays": 90,
  "ipWhitelist": ["10.0.0.0/8"],
  "rateLimit": 1000
}

Key Rotation

Rotation creates a new key and schedules the old key for revocation after a grace period. During the grace period, both keys are valid.

1. Initiate: POST /api/v1/api-keys/:keyId/rotate -- returns the new key
2. Check status: GET /api/v1/api-keys/:keyId/rotation-status
3. Complete early: POST /api/v1/api-keys/:keyId/rotation/complete -- revokes old key immediately
4. Cancel: POST /api/v1/api-keys/:keyId/rotation/cancel -- keeps old key, revokes new key

Error Codes