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

TokenPrefixHow to get oneFor
API keyv12p_Create it in Settings → Developer; see Create an API key.Scripts and CI
OAuth access tokenv12a_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

ScopeLabelAllows
user:readView account and membersThe member directory: usernames, emails and roles. Any key reads its own account, organization and credit balance without it.
repos:readView repositories and SteersRepositories, branches, pull requests, tags, Steer instructions and Autopilot rules.
repos:writeAdd repositoriesAdd public repositories to the workspace. Owners can also add private repositories granted by GitHub, create repositories V12 hosts and push code to them.
steers:writeManage SteersCreate, edit, archive and restore Steers. Archiving detaches them from Autopilot rules; finding tags and run history are kept.
autopilot:writeManage AutopilotAdd, 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:readView runsRuns, their progress and context documents.
runs:writeCreate runsEstimate and start runs; add or archive context documents.
runs:manageManage runsCancel runs.
runs:shareShare runsCreate, change and revoke guest links that open a run to people outside the organization.
findings:readView findingsThe inbox: findings, their status, reports and comments.
findings:writeEdit findingsChange 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 tool get_me) needs no scope: any valid token reads its own user, workspace and token.
  • GET /runs/{run}/findings (MCP tool list_run_findings) needs both runs:read and findings: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.

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:

ActionWho can
Add a private repositoryAdmin
Create a hosted repository or get its push URLAdmin
Archive a context document someone else createdAdmin
Add, change, pause or remove an Autopilot ruleAdmin
List or change a run's guest linksAdmin, 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.

BucketLimitWindowWhat counts
ip3,0001 minuteEvery REST and MCP request
mcp1,5001 minuteEvery authenticated MCP request
reads1,2001 minuteOperations that read
findings:write1201 minuteFinding changes and comments; a bulk change counts once per finding
runs:estimate301 hourRun estimates, and the estimate a run start without a quote makes
runs:write201 hourRun 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:manage601 minuteRun cancellations and guest link changes
repos:write6010 minutesAdding repositories, through the API or in the app; creating hosted repositories and push URLs through the API
autopilot:write6010 minutesAdding, changing and removing Autopilot rules over MCP
documents6010 minutesUpload slots, new documents and archiving
  • A response reports the budget its request charged in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). On REST that is the budget of the operation that ran, or ip when the request was refused before it: no token, a missing scope, invalid input, an unknown path or a wrong method. On MCP it is ip until the token is verified and mcp on 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, with X-RateLimit-Remaining: 0.
  • These responses carry no X-RateLimit-* headers: OPTIONS preflights, GET /api/v2/openapi.json, /api/v1, any method but POST on /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 the ip bucket in its headers; MCP responses always report the mcp bucket. 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.

SymptomCauseFix
401 unauthenticated, and WWW-Authenticate has no errorNo 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_scopeThe 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:writeKeys 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:writeKeys 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 forbiddenYour role doesn't allow the action.Ask an Admin.
404 not_found for something you can see in the appThe 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_visibleGitHub 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_limitedA 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_errorAn unexpected failure inside V12.Retry once. If it persists, report it with the requestId.

On this page