Authentication and permissions

Every request to the REST API or the MCP server carries one token. This page covers which tokens work, what a token may do, and why a request is refused.

Credentials

Two kinds of token work:

• API keys start with v12p_. You create them in Settings → Developer; see Create an API key. They suit scripts and CI.
• OAuth access tokens start with v12a_. MCP clients and the v12 CLI get one when you sign in through the browser and approve the consent page.

Send the token in the Authorization header as Bearer <token>. The API looks nowhere else: a token in a cookie or in the query string is ignored.

Scopes

A token's scopes decide which operations it can call:

• The Create key dialog starts with no scope ticked, and a key needs at least one.
• Starting a run spends credits, so the consent page marks Create runs with Uses credits.
• GET /runs/{run}/findings (the MCP tool list_run_findings) needs both runs:read and findings:read.
• An MCP client sees only the tools its token's scopes allow.
• v12 auth login asks for every scope unless you pass --scopes.
• A missing scope gets 403 insufficient_scope. details.required lists the scopes the operation needs, and so does scope in the WWW-Authenticate header.

The REST reference lists the scopes each endpoint needs.

Which organization a token reads

Each token reads exactly one workspace, and the API cannot switch it:

• An API key reads the workspace that was active when you created it.
• An OAuth token reads the workspace named on the consent page: the one active in the app when you signed in.

The consent page shows:

• the app: Authorize V12 CLI for V12's own CLI, or "app wants to access V12" with a Third-party app tag for anything else;
• your username and email, with Not you? to sign in as someone else;
• the workspace's name, marked "Personal workspace" or "Organization";
• the scopes the app asks for, grouped under Read and Act;
• Cancel and Authorize followed by the app's name.

The consent page has no workspace picker. To connect an app to another workspace:

An id from another workspace gets 404 not_found, even when you belong to both.

Organization permissions

A token can do only what its user's role allows in the workspace, and the API checks the role on every request, so a role change applies at once.

Admins and Members can both call every operation. The one exception: archiving a context document that someone else created needs an Admin, and a Member gets 403 forbidden. In GET /members, Admins have the role owner.

When access ends

The API answers 401 unauthenticated when:

• the API key was revoked;
• the OAuth token expired, or its app was revoked under Authorized apps, which "invalidates its tokens immediately";
• you changed or reset your password, which revokes every API key and OAuth token you hold, in every workspace;
• your membership in the workspace was removed;
• your account was suspended.

v12 auth logout revokes the CLI's OAuth tokens before it deletes them from your machine.

Rate limits

Budgets count per user, across all of your tokens and across REST, MCP and the CLI. The ip budget counts per IP address instead, before the token is checked.

• Each response reports the bucket it charged in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the seconds until the window resets.
• Over a limit, the API answers 429 rate_limited with a Retry-After header, and details.bucket names the bucket.
• Run estimates, run starts and document operations also share a limit of 60 a minute per user with the same actions in the app.
• If the rate limiter itself is down, reads carry on, but findings:write, runs:estimate, runs:write, runs:manage and documents answer 503 rate_limit_unavailable with Retry-After: 30.

Troubleshooting

Every error body carries a requestId. Keep it when you report a problem.