API keys
Keys are minted from the accounts dashboard — there is no API for minting keys (mint flow requires a logged-in human). Sign in to accounts.zerowidth.ai, open Workspace → API keys, click New API key.
Two kinds of key
Pick the kind at mint time. The kind drives what the key can see.
userkindMember-minted personal key. Sees the same flows you see when signed in via the dashboard — your PRIVATE flows plus everything visible to the workspace. Auto-revoked when you leave the workspace or delete your account. Any workspace member can mint their own user key.
workspacekindAdmin-minted, full-workspace reach. Sees every flow in the workspace including PRIVATE flows owned by other members. Used for shared infrastructure — CI runners, production services, ZeroWidth-side integrations. OWNER or ADMIN required to mint, because the gate is admin trust.
The shape that makes a workspace key surprising: someone with a leaked workspace key has the reach of an admin. Hand them out deliberately. Each row in the dashboard shows who minted the key, for traceability.
Scopes
Every key carries a scope allowlist. Each endpoint declares the scope it requires; the auth layer rejects the request if the key doesn't carry it. Scopes are forever-stable strings — they will never be renamed once shipped.
| Scope | What it allows |
|---|---|
workbench:flows:run | Execute Workbench flows via POST /1.0/flows/:flowUuid/runs. |
workbench:flows:read | List flows + read definitions, metadata, run history. (Endpoints coming.) |
workbench:flows:write | Create, update, duplicate, delete flows. (Endpoints coming.) |
workbench:knowledge_bases:read | List knowledge bases + read one in full — reference. |
workbench:knowledge_bases:search | Retrieve chunks from a knowledge base — search. Separate from read because semantic search spends inference credit per query. |
workbench:knowledge_bases:write | Create knowledge bases + add documents (ingestion spends credit). |
caliper:datasets:read | List datasets + read items and metadata. (Endpoints coming.) |
caliper:datasets:write | Create, update, delete datasets and their items. (Endpoints coming.) |
caliper:reviews:read | Read reviews, rubric snapshots, per-item ratings. (Endpoints coming.) |
caliper:reviews:write | Create reviews, submit ratings, manage reviewers. (Endpoints coming.) |
caliper:evals:read | Read an eval + its bound dataset items — the CI scoring loop. |
caliper:evals:write | Submit eval runs for scoring. |
compass:pages:read | Read Compass pages, search, and connections — via the MCP server. |
compass:pages:write | Create Compass pages and typed connections — via MCP. |
Quick-pick templates in the mint UI:
- Run flows —
workbench:flows:run. The safe default for a key that only needs to invoke flows. - CI evals —
caliper:evals:read+caliper:evals:write. For scoring in CI. - Full access — every scope. For trusted infrastructure where granularity isn't worth the bookkeeping.
Cost cap
Every key has an optional lifetime spend ceiling in USD. The system sums the cost of every run made by the key; once the running total reaches the cap, new runs are denied with 402 plan_limit. The cap is the leaked-key safety net — if a key ends up in a public repo, it burns at most this amount before stopping.
New keys default to $10. Set to Unlimited (null) explicitly for trusted infrastructure. The dashboard displays running spend ($X.XX of $Y.YY) per key.
Revocation
Workspace admins can revoke any key. Members can revoke their own personal keys. Revocation is immediate — the next request returns 401 auth_invalid. The revoked key is retained in the dashboard so historical run logs still show which key produced them; you cannot un-revoke.