API keys
Keys are minted from the accounts dashboard; there's no API for minting them. 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 — 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 other members' Private flows. Used for shared infrastructure — CI runners and production services. Only an owner or admin can mint one.
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, and a request without it is rejected. Scopes are forever-stable strings — they will never be renamed once shipped.
The mint screen lists every scope your workspace can grant, grouped by product. The ones below are the ones you'll reach for most. A scope covers the same ground whether the caller is your code over REST or an assistant over MCP.
| Scope | What it allows |
|---|---|
workbench:flows:run | Run flows — POST /1.0/flows/:flowUuid/runs — and start task runs. |
workbench:flows:read | List flows and read their definitions, metadata, and run history. |
workbench:flows:write | Create, update, duplicate, and delete flows. |
workbench:knowledge_bases:read | List knowledge bases + read one in full — reference. |
workbench:knowledge_bases:search | Retrieve chunks from a knowledge base — search. Each query spends inference credit. |
workbench:knowledge_bases:write | Create knowledge bases + add documents (ingestion spends credit). |
workbench:shims:read | List shims, read one, and fetch the published weights. |
workbench:shims:write | Create shims and add answers and examples — what an assistant over MCP uses to write examples for you. |
caliper:datasets:read | List datasets and read their items. |
caliper:datasets:write | Add to datasets and change them, including sending feedback from your own product. |
caliper:reviews:read | Read reviews, rubric snapshots, and per-item ratings. |
caliper:reviews:write | Create reviews, submit ratings, manage raters. |
caliper:evals:read | Read an eval and its bound dataset items — the CI scoring loop. |
caliper:evals:write | Submit eval runs for scoring. |
caliper:traces:write | Send traces from your agent, directly or with OpenTelemetry. Can't read anything back. |
caliper:sources:read | Find sources and read what their agents did. |
ledger:metrics:read | Read metrics and their readings — reference. |
ledger:metrics:write | Send readings, one at a time or in batches. |
ledger:entries:read | Read decisions, their expectations, and how they settled. |
ledger:entries:write | Record decisions and settle them. |
compass:pages:read | Read Compass pages, search, and connections. |
compass:pages:write | Create Compass pages and typed connections. |
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. Every run made with the key counts toward it; once the total reaches the cap, further runs return 402 plan_limit. If a key ever leaks, it can spend at most this much before it stops.
New keys default to $10. Set it to Unlimited 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.