Authentication & API keys
Scoped, revocable bearer keys — mint, rotate, revoke, and the scope model
Every API request authenticates with a bearer key:
curl -s $BASE_URL/v1/me -H "Authorization: Bearer ds_live_..."API keys authenticate the /v1 API only. The legacy /api/* routes are
the web app's private, cookie-authenticated surface — a key used there gets a
typed 403 pointing back here.
Keys are minted at Settings → API keys (or via
POST /v1/keys with an existing admin key). The secret is shown once;
DeepSieve stores only a hash.
Scopes
A key holds resource:action scopes; a request needs the route's scope or it
gets 403 insufficient_scope. Presets:
| Preset | Scopes | Use for |
|---|---|---|
| Agent (default) | runs:*, data:read, reports:*, export:read, blueprint:read, blueprint:create (create-only), blueprint:propose (ask-only), webhooks:* | coding assistants, agents — can start runs (prepaid credits; cap with a per-key budget), manage reports, and create NEW Blueprints. Editing the active Blueprint is human-only regardless of scopes |
| Read-only | all :read scopes | dashboards, sync jobs |
| Full | everything except platform admin | trusted backends |
Custom scope lists: POST /v1/keys {"name": "...", "scopes": ["runs:read", ...]}.
A key can never exceed its minter: it stores the minter's role, and a key can't
mint or rotate its way to scopes it doesn't hold.
Some scopes require another, and we add it for you. blueprint:propose
requires data:read: the propose response contains the Blueprint's full spec,
so it asks the same rights as reading that spec directly. Request
blueprint:propose on its own and the key is created with data:read as well,
rather than failing at its first call. The scopes array in the response is
what was actually granted — compare it with what you asked for to see any
addition. Nothing unrelated to your request is ever added.
Rotate and revoke
curl -s -X POST $BASE_URL/v1/keys/{key_id}/rotate -H "Authorization: Bearer ds_live_..."Rotation returns a new secret; the old one keeps working for 24 hours so you
can redeploy without downtime. DELETE /v1/keys/{key_id} revokes immediately.
Optional per-key limits
At mint time you can set expiry, a workspace pin, and budgets — in the
create-key dialog (expiry + budgets) or via POST /v1/keys (expires_at,
workspace_id, budget_runs, budget_cents). A key at its budget gets
402 budget_exceeded — the agent should stop and alert a human. Combined with
prepaid billing, the worst an agent can do is exhaust its budget and stop; a
key can never generate an invoice.
Browser login for MCP (OAuth 2.1)
When you add DeepSieve to a coding agent over --transport http, you don't
paste a key — the client runs an OAuth 2.1 browser flow. The consent screen is
DeepSieve's own login (via our identity provider); it grants a research +
read session (runs:*, data:read, reports:read), never billing or
key-management scopes — a browser session is a person, not a service
credential. Tokens are short-lived and refresh silently; revoke a client's
access from your account without affecting your API keys. Discovery follows
RFC 9728: the endpoint advertises itself at
/.well-known/oauth-protected-resource. Use an API key instead for CI,
containers, and server-to-server, where no browser exists.