Authentication and permissions
API keys and OAuth, scopes, organization binding, rate limits, and fixing 401, 403 and 429.
Every request to the REST API or the MCP server carries one token. Its scopes, its workspace and your role limit what it can do.
Credentials
| Token | Prefix | How to get one | For |
|---|---|---|---|
| API key | v12p_ | Create it in Settings → Developer; see Create an API key. | Scripts and CI |
| OAuth access token | v12a_ | Sign in through the browser and approve the consent page. | MCP clients and the v12 CLI |
Send the token only in the Authorization header, as Bearer <token>. The API ignores a token in a cookie or the query string.
Scopes
| Scope | Label | Allows |
|---|---|---|
user:read | View account and members | The member directory: usernames, emails and roles. Any key reads its own account, organization and credit balance without it. |
repos:read | View repositories and Steers | Repositories, branches, pull requests, tags, Steer instructions and Autopilot rules. |
repos:write | Add repositories | Add public repositories to the workspace. Owners can also add private repositories granted by GitHub, create repositories V12 hosts and push code to them. |
steers:write | Manage Steers | Create, edit, archive and restore Steers. Archiving detaches them from Autopilot rules; finding tags and run history are kept. |
autopilot:write | Manage Autopilot | Add, change, pause and remove Autopilot rules. Rules start paid runs on pushes, pull requests or a schedule without a price limit. Needs the Admin role. |
runs:read | View runs | Runs, their progress and context documents. |
runs:write | Create runs | Estimate and start runs; add or archive context documents. |
runs:manage | Manage runs | Cancel runs. |
runs:share | Share runs | Create, change and revoke guest links that open a run to people outside the organization. |
findings:read | View findings | The inbox: findings, their status, reports and comments. |
findings:write | Edit findings | Change status, comment and update triage decisions. |
- A key needs at least one scope. The Create key dialog starts with none ticked.
GET /api/v2/me(MCP toolget_me) needs no scope: any valid token reads its own user, workspace and token.GET /runs/{run}/findings(MCP toollist_run_findings) needs bothruns:readandfindings:read.- Starting a run spends credits, so the consent page marks Create runs with Uses credits.
- An MCP client sees only the tools its token's scopes allow.
The REST reference lists the scopes each endpoint needs.
Steer management and steers:write
steers:write is opt-in and requires an explicit scope request and consent. Existing tokens, omitted-scope sign-ins and the Full access preset do not gain it. For the CLI, use v12 auth login --scopes repos:read,steers:write and include any other scopes you need. For an API key, select Manage Steers. Reads remain under repos:read; writes additionally require your current workspace role to permit managing Steers.
Autopilot rules and autopilot:write
autopilot:write lets an MCP client add, change, pause and remove Autopilot rules. It is not opt-in: sign-ins that omit scope, the MCP sign-in challenge and the Full access key preset include it. Keys and app connections approved before V12 offered Manage Autopilot don't have it. Reading rules needs only repos:read; changing them also needs the Admin role. These tools are MCP-only; see Autopilot rules.
Guest links and runs:share
runs:share is opt-in: a key or app holds it only when it asks for it by name. An omitted scope, the MCP sign-in challenge, the MCP server's discovery metadata and the Full access key preset never include it. v12 auth login asks for every scope but runs:share and steers:write unless you pass --scopes.
Listing and revoking guest links need only runs:share. Creating or changing a link also needs findings:read, and a comment or triage link also needs findings:write, so a token can't make a link that does more than the token can.
Which organization a token reads
Each token reads exactly one workspace, and the API can't switch it. REST paths name it by its slug, /api/v2/orgs/<org>/…; see Addresses.
- 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.
A path that names another workspace's slug gets 404 not_found, even when you belong to both. So does a finding, run or document of another workspace.
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 requested scopes, 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:
If the app is already connected, revoke it under Settings → Developer → Authorized apps while its current workspace is active.
Switch to the other workspace: open the account menu at the bottom of the sidebar and pick it under Organizations.
Connect the app again. The consent page now names the new workspace.
Organization permissions
A token can do only what its user's role allows in the workspace. The API checks the role on every request, so a role change applies at once.
Admins and Members can both call almost every operation. These get 403 forbidden for anyone else:
| Action | Who can |
|---|---|
| Add a private repository | Admin |
| Create a hosted repository or get its push URL | Admin |
| Archive a context document someone else created | Admin |
| Add, change, pause or remove an Autopilot rule | Admin |
| List or change a run's guest links | Admin, or the run's owner |
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 your tokens and across REST, MCP and the CLI. The ip budget counts per network instead, before the token is checked: an IPv4 address, or the /64 prefix an IPv6 address belongs to.
| Bucket | Limit | Window | What counts |
|---|---|---|---|
ip | 3,000 | 1 minute | Every REST and MCP request |
mcp | 1,500 | 1 minute | Every authenticated MCP request |
reads | 1,200 | 1 minute | Operations that read |
findings:write | 120 | 1 minute | Finding changes and comments; a bulk change counts once per finding |
runs:estimate | 30 | 1 hour | Run estimates, and the estimate a run start without a quote makes |
runs:write | 20 | 1 hour | Run starts; a retry with the same key, or a start refused before billing for its quote, repository, scope, price or documents, doesn't count. A start refused because its quoted change or commit moved (quote_stale) counts |
runs:manage | 60 | 1 minute | Run cancellations and guest link changes |
repos:write | 60 | 10 minutes | Adding repositories, through the API or in the app; creating hosted repositories and push URLs through the API |
autopilot:write | 60 | 10 minutes | Adding, changing and removing Autopilot rules over MCP |
documents | 60 | 10 minutes | Upload slots, new documents and archiving |
- A response reports the budget its request charged in
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(seconds until the window resets). On REST that is the budget of the operation that ran, oripwhen the request was refused before it: no token, a missing scope, invalid input, an unknown path or a wrong method. On MCP it isipuntil the token is verified andmcpon every response after, JSON-RPC errors included; a tool's own budget is charged too but never reported. A 429 reports the budget it ran out of, withX-RateLimit-Remaining: 0. - These responses carry no
X-RateLimit-*headers:OPTIONSpreflights,GET /api/v2/openapi.json,/api/v1, any method butPOSTon/api/mcp, a REST path with a malformed percent escape or a segment over 255 characters, and a request refused while the API is disabled. - Only work counts. A request refused for a missing scope or permission, or for a field outside its schema in the API reference (missing, of the wrong type, or out of range), spends no operation budget. A value the operation checks itself, such as a full review without
scope, a malformed scope path or one that names nothing V12 reviews, or an unsupported document type, still counts. REST then reports theipbucket in its headers; MCP responses always report themcpbucket. A run start counts once it reaches billing, even if billing then refuses it. - 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 is down, requests are still served and still limited: each V12 server counts the budgets itself until the limiter is back.
Troubleshooting
Every error body carries a requestId. Keep it when you report a problem. The error reference lists every other code.
| Symptom | Cause | Fix |
|---|---|---|
401 unauthenticated, and WWW-Authenticate has no error | No Authorization header reached the API. | Send Authorization: Bearer <token>. |
400 invalid_request with details.field: "Authorization" | The header isn't exactly Bearer and one token: another scheme, a comma, or extra text. | Send one token after Bearer . |
401 unauthenticated with error="invalid_token" | The token isn't a V12 token, or access ended: see When access ends. | Create a new key, or sign in again. |
403 insufficient_scope | The token lacks a scope. details.required, and scope in the WWW-Authenticate header, list the scopes the operation needs. | Create a key with those scopes, or connect the app again and approve them. |
403 insufficient_scope naming repos:write | Keys and app connections approved before V12 offered Add repositories don't have it. A refreshed token keeps the scopes it was approved with. | Create a key with Add repositories, or sign in again (v12 auth login, or reconnect the app) and approve it. |
403 insufficient_scope naming autopilot:write | Keys and app connections approved before V12 offered Manage Autopilot don't have it. | Create a key with Manage Autopilot, or sign in again and approve it. |
403 forbidden | Your role doesn't allow the action. | Ask an Admin. |
404 not_found for something you can see in the app | The token reads another workspace, or the path names another workspace's slug. | Use organization.slug from GET /api/v2/me in the path. See Which organization a token reads. |
404 repository_not_visible | GitHub shows V12 no public repository by that name, and the workspace's GitHub connection doesn't include it. | Check the name. If it's private, follow details.recovery, or ask an Admin to give V12's GitHub App access to it. |
429 rate_limited | A budget is spent; details.bucket names it, and Retry-After says when to retry. With details.source: "github", GitHub is limiting V12's requests instead, and there is no Retry-After. | Wait Retry-After seconds, then retry. For GitHub, try again in a few minutes. |
500 internal_error | An unexpected failure inside V12. | Retry once. If it persists, report it with the requestId. |