Authentication

9thSense uses API key authentication. Every request (except open paths) must include the X-Api-Key header.

X-Api-Key: zk_live_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef

Key Format

New keys follow the split-key pattern:

zk_<env>_<prefix>_<secret>

• zk — fixed literal prefix
• <env> — the environment the key is bound to (e.g. live, test). Keys created before environments existed have no env segment: zk_<prefix>_<secret>
• <prefix> — 12-character hex token stored in plaintext for fast index lookup
• <secret> — 32-character hex token; the full key is verified with bcrypt

This approach allows O(1) DB lookup by prefix while never storing the secret in recoverable form.

Legacy keys (SHA-256 hashed, no prefix) are still accepted for backward compatibility. New keys should always use the split-key format.

Scopes

Each key carries one or more scopes from a 19-scope catalog, and each endpoint requires one of them. ✋ marks the scopes for which a tenant member's key needs an org admin's approval.

tenant:admin includes tenant:read and tenant:write. No other scope implies another, so a key that both reads and creates cases needs ["case:read", "case:write"]. The legacy read, write and admin names are rejected with 422 on new requests; existing keys were migrated to the equivalent catalog scopes. Approval: members can request any scope; privileged (✋) ones, including tenant:admin, wait for an org admin. Until one approves, the key gets 401 API key pending approval. Requests pending 14 days are rejected automatically.

Key Management

Keys are managed from the dashboard, or with these routes using a dashboard session (Authorization: Bearer <jwt>). They are role-gated, so an API key calling them gets 403, whatever its scopes.

Create API Key

Request body:

Example request:

{
  "name": "Production Integration",
  "environment": "live",
  "scopes": ["case:read", "case:write", "document:write"],
  "expires_in_days": 90
}

Example response (201):

{
  "key": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Production Integration",
    "prefix": "a1b2c3d4e5f6",
    "environment": "live",
    "scopes": ["case:read", "case:write", "document:write"],
    "status": "active",
    "owner": null,
    "created_at": "2026-03-25T10:00:00Z",
    "expires_at": "2026-06-23T10:00:00Z",
    "last_used_at": null,
    "revoked_at": null,
    "purge_at": null,
    "approval": null
  },
  "secret": "zk_live_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef"
}

---

List API Keys

Query parameters:

Returns a JSON array of key resources (the key object above). The secret is never included.

---

Revoke API Key

Path parameters:

Returns 200 with the updated key ("status": "revoked"). Returns 404 if the key does not exist and 409 if it is already revoked. To remove a revoked key permanently, call DELETE /v1/admin/keys/{key_id} (204).

---

Error Responses