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",
  "name": "Production CLI",
  "prefix": "od_live_",
  "last4": "k39q",
  "createdAt": "2026-03-14T11:20:00Z",
  "lastUsedAt": "2026-04-17T09:00:00Z",
  "revokedAt": null
}

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",
      "name": "Production CLI",
      "prefix": "od_live_",
      "last4": "k39q",
      "createdAt": "2026-03-14T11:20:00Z",
      "lastUsedAt": "2026-04-17T09:00:00Z",
      "revokedAt": null
    },
    {
      "id": "key_def456",
      "name": "Default",
      "prefix": "od_live_",
      "last4": "xz11",
      "createdAt": "2026-01-10T12:00:00Z",
      "lastUsedAt": null,
      "revokedAt": "2026-02-01T08:30:00Z"
    }
  ]
}

Revoked keys remain in the list — the dashboard hides them behind a filter, but the API returns them so audit consumers see the full history.

POST /api/v1/api-keys​

Create a new API key.

Request body​

{ "name": "CI publisher" }
  • name is a 1–100 character human label — shown in the dashboard and in this list response.

Success response​

Status 201.

{
  "id": "key_ghi789",
  "name": "CI publisher",
  "plaintext": "od_live_r7t9QxKm8zBvN3wY2hLp4dFaS1cE6uJo",
  "prefix": "od_live_",
  "last4": "6uJo",
  "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 prefix + "…" + last4. If you lose it, revoke it and create a new one — there is no recovery path.

Errors​

StatuserrorWhen
400no_workspaceCaller hasn't completed onboarding yet
400invalid_requestname missing or > 100 chars
401unauthorizedNo session cookie

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.