PAT scopes

A personal access token (bbpat_…) carries a list of permission scopes, fixed when the token is minted. This page states exactly which scopes exist, what each one grants today, and which endpoints check them.

Two independent axes

Two separate things are called "scope" in the product, and they are checked independently. A request has to satisfy both.

Every PAT from brainbase token create is user-wide. Resource-scoped PATs exist, but only Brainbase mints them — see Resource scope.

Permission scopes

brainbase token create accepts a comma-separated list. Three values are allowed; anything else is rejected locally before the request is sent, and again by the server.

brainbase token create --name ci                       # scopes: read, publish
brainbase token create --name ci-readonly --scopes read
brainbase token list                                   # scopes per token

Two further scopes exist in the platform and are enforced, but you cannot mint them: the token endpoint rejects anything outside read, publish and admin. They are issued internally to the credentials Brainbase plants in a sandbox, listed here so an unfamiliar scope name in an error is identifiable.

Scopes are immutable. token rename changes only the label; to change what a token can do, mint a replacement and revoke the old one.

What is actually enforced

On the CLI control plane at /v2/cli, every write requires the publish scope: all 23 mutating endpoints carry the check. Of the 20 read endpoints, 17 require no scope and three — the surface-settings reads behind agent surface — require read.

The same check refuses an agent task key (bb_live_…) outright on every endpoint in the table above that names a scope, with CLI task keys cannot manage cloud configuration.

Outside /v2/cli the rule is patchier. Some writes check publish unconditionally: agent secrets, file uploads, thread creation, orchestration writes, and the benchmark mutations. Others are covered only by a newer blanket guard that is deployed but not yet enforcing — it is gated on a server setting that currently logs a would-be denial and lets the request through. Templates, machines, evals, alerts, orchestration templates and most of PATCH /v2/agents/{agent_id} sit in that group.

The check applies to PATs only. A browser login session is a Supabase JWT and carries no scope list, so it is never scope-checked and can always write whatever the user's role allows.

Error responses

A token without the scope a write needs gets 403 before the handler runs, so nothing is created or modified:

{
  "detail": "PAT lacks required scope: publish"
}

Two nearby failures that are not scope failures, and have different fixes:

Resource scope

Independently of read/publish/admin, a credential is either user-wide or bound to exactly one resource. The intent is that a resource-bound credential cannot reach routes that configure things above a single resource — orgs, teams, agent creation — even when it carries publish.

With strict admission enabled, alert creation, changes, deletion and signing-secret rotation, plus agent and orchestration template writes, also require a person's session or user-wide PAT under the existing group or team permissions. Resource credentials receive 403 with detail.code: agent_credential_refused before configuration is saved. Task model and metadata updates distinguish execution settings from ordinary label edits. Reads retain their existing permissions. Strict admission is off by default and requires both INTEGRATION_CONTROL_ENABLED=true and cutover:strict_admission=true, independently of tier shadow mode. If the master switch is on but the strict-admission setting cannot be read, protected resource writes return 503 with detail.code: origin_unavailable and Retry-After: 5.

Strict admission also confines runtime-event writes to the credential's own task or a task it delegated to in the same context. A sandbox PAT cannot write another context's transcript just because both tasks use the same agent. Both /internal/events and /v2/internal/events apply this rule before saving events or starting terminal-event work. Existing exact task-key scope and human/service authorization still apply. Cross-context or ambiguous task identifiers return 403 with detail.code: cross_context; writes from a child into its parent return detail.code: not_descendant. Strict-off behavior is unchanged.

The refusals read differently. GET /orgs/{org_id}/teams/{team_id}/agents and GET /orgs/{org_id}/members answer with the credential_scope_denied object listed above. The orchestration endpoints answer with a plain string naming the binding, for example agent-scoped PATs cannot access orchestration configuration. The surface endpoints accept a user-wide or agent-bound credential and refuse anything narrower with Surface settings require a user or agent credential.

You cannot mint a resource-scoped PAT from the CLI, and you do not need to: the resource-scoped tokens an agent uses are planted in its sandbox automatically. The distinction matters when reading an error — a 403 naming credential_scope_denied came from a token Brainbase minted for a sandbox, not from a token you created.

Which credential each surface accepts

A PAT and a login session are not interchangeable everywhere. Three rules cover it:

• Minting or changing PATs requires a login session. token create, rename and revoke reject a PAT with jwt_required. token list accepts a user-level PAT.
• Everything else on the control plane accepts either. A PAT with the right scopes can do anything a session can, subject to the scope rules above.
• Some commands call the web app, not the control plane, and need a session. brainbase integrations and the provider operations of agent surface — GitHub and Linear setup, the Linear manifest and disconnect, and phone search, purchase and release — refuse while BRAINBASE_TOKEN is set.
• Saved PATs are a fallback for every authenticated command. BRAINBASE_TOKEN takes priority, then a valid or renewable login session, then a usable saved PAT. See Authentication.