/v1/keys — API Key Management

Authenticated by user session (the JWT used by the dashboard), not by API key — these endpoints manage your keys, so they live one level up from key auth.

In local mode, all /v1/keys endpoints return 503 — local mode has no signup or key management surface (the gateway accepts any token).

POST /v1/keys — mint a new key

Creates a key. Returns the full key string ONCE. Store it immediately; the gateway only persists the argon2id hash.

Request

{
  "name": "Production app",
  "pipelineConfig": "exact-cache,semantic-cache,cost-guard,patterns"
}

Both fields optional. name ≤ 120 chars. pipelineConfig ≤ 8000 chars.

Response (201)

{
  "id": "5b3e...",
  "key": "prxy_live_a1b2c3d4e5f6...",
  "prefix": "prxy_live_a1",
  "name": "Production app",
  "pipelineConfig": "exact-cache,semantic-cache,cost-guard,patterns",
  "createdAt": "2026-04-27T18:32:11.123Z"
}

GET /v1/keys — list keys

Lists every non-deleted key for the authenticated user. Hashes are never returned.

Response

{
  "keys": [
    {
      "id": "5b3e...",
      "prefix": "prxy_live_a1",
      "name": "Production app",
      "pipelineConfig": "exact-cache,semantic-cache,cost-guard,patterns",
      "createdAt": "2026-04-27T18:32:11.123Z",
      "lastUsedAt": "2026-04-27T19:14:02.000Z",
      "revokedAt": null
    }
  ]
}

PATCH /v1/keys/:id — update name or pipeline config

Request

{
  "name": "Renamed",
  "pipelineConfig": "exact-cache,patterns"
}

Either field is optional. Pass pipelineConfig: null to clear it (falls back to env var or default).

Response

{
  "ok": true,
  "key": { "id": "5b3e...", "prefix": "...", "name": "Renamed", "pipelineConfig": "exact-cache,patterns", ... }
}

The gateway invalidates the auth cache for this key — config changes are visible to subsequent requests immediately.

DELETE /v1/keys/:id — revoke

Marks the key as revoked. Soft delete — the row is kept for audit.

Response (204)

Empty body. The key starts returning 401 on its next request.

Errors