API keys

API keys are the only credential the API accepts. Each key is bound to exactly one organization and a set of scopes.

Lifecycle

1. Create — POST /v1/api-keys returns the secret once.
2. Use — pass via X-API-Key on every request.
3. Rotate — create a replacement, deploy, then revoke the old one.
4. Revoke — DELETE /v1/api-keys/:id. Effective globally in under 60s.

Storage shape

The server stores only an Argon2id hash of the secret plus the first 8 characters (the "prefix"). Even an Oligon engineer staring at the database cannot read your key.

-- simplified
CREATE TABLE api_keys (
  id            TEXT PRIMARY KEY,
  org_id        TEXT NOT NULL REFERENCES orgs(id),
  prefix        TEXT NOT NULL,     -- "sk_live_K2J9"
  secret_hash   BYTEA NOT NULL,    -- argon2id(secret)
  scopes        TEXT[] NOT NULL,
  expires_at    TIMESTAMPTZ
);

Expiry

Keys can carry an expires_at value. After that, requests return 401 expired_api_key. We email all admin members 14 days, 3 days, and 24h before expiry.

Publishable keys

A pk_publishable_… key is safe to ship in browsers. It can only:

• POST /v1/extract (with strict per-IP rate limits)
• read receipts whose created_by matches the calling session

This is what powers the browser direct-upload guide.