Skip to main content

API keys

Programmatic management of the od_live_* keys that authenticate the CLI, agents, and backend integrations. See Authentication for how a key is used once issued.

Session auth only

Every endpoint on this page requires a browser session cookie. API keys can't create or revoke other API keys — an API key calling these endpoints returns 401 unauthorized.

The dashboard UI under Dashboard → API Keys is a thin wrapper over these three endpoints; anything it does, you can do from the API.

The key record​

List responses carry the redacted shape:

{
  "id": "key_abc123",
  "label": "Production CLI",
  "keyHint": "k39q",
  "createdAt": "2026-03-14T11:20:00Z",
  "lastUsedAt": "2026-04-17T09:00:00Z"
}

The full plaintext key is only returned once, from POST /api/v1/api-keys at creation. See below.

GET /api/v1/api-keys​

List the caller's API keys (redacted).

Response​

{
  "keys": [
    {
      "id": "key_abc123",
      "label": "Production CLI",
      "keyHint": "k39q",
      "createdAt": "2026-03-14T11:20:00Z",
      "lastUsedAt": "2026-04-17T09:00:00Z"
    },
    {
      "id": "key_def456",
      "label": "Default",
      "keyHint": "xz11",
      "createdAt": "2026-01-10T12:00:00Z",
      "lastUsedAt": null
    }
  ]
}

Revoked keys are not returned by this endpoint. Revocation history is kept server-side for audit events, but active API consumers only see keys that can still authenticate.

POST /api/v1/api-keys​

Create a new API key.

Request body​

{
  "workspaceId": "ws_abc123",
  "name": "CI publisher"
}
  • workspaceId is the workspace the key is scoped to. The caller must be an active member of that workspace.
  • name is a 1–100 character human label. The stored key record calls this field label in responses.

Success response​

Status 201.

{
  "id": "key_ghi789",
  "label": "CI publisher",
  "keyHint": "6uJo",
  "plaintext": "od_live_r7t9QxKm8zBvN3wY2hLp4dFaS1cE6uJo",
  "createdAt": "2026-04-17T10:15:00Z"
}
One-time plaintext

plaintext is the only time the full key is returned. The dashboard and every subsequent GET /api-keys response shows only the last four characters in keyHint. If you lose it, revoke it and create a new one — there is no recovery path.

Errors​

StatuserrorWhen
400invalid_requestworkspaceId or name missing, or name > 100 chars
401unauthorizedNo session cookie
403forbiddenCaller isn't an active member of workspaceId

Auto-created keys​

When a new user completes onboarding and creates their first workspace, OpenDocs auto-creates a first API key named Default and returns it in the onboarding response. You don't need to call this endpoint separately for the very first key — see Onboarding and profile.

DELETE /api/v1/api-keys/:keyId​

Revoke a key.

Response​

{ "success": true }

Errors​

StatuserrorWhen
404not_foundKey doesn't exist or isn't owned by the caller

Revocation semantics​

  • Revocation is immediate. The next request carrying the revoked key returns 401 unauthorized.
  • In-flight requests already past auth continue to completion — this matters for long-running SSE streams like batch publish. Revoke, wait for outstanding streams to close, rotate.
  • Revocation is not reversible. If you revoke the wrong key, create a new one and update the caller.

Key prefix and shape​

Every live key starts with:

od_live_

The full key is 40 characters: the od_live_ prefix plus 32 characters of random entropy. Keys are long-lived — there is no built-in expiry. The only way to invalidate a key is to revoke it.