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, the rule has no exceptions: every write requires the publish scope, and no read requires any scope. All 13 mutating endpoints carry the check; all 15 read endpoints carry none.

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.

The two refusals also read differently. GET /orgs/{org_id}/teams/{team_id}/agents answers 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.

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 and managing PATs requires a login session. token create, list, rename and revoke all reject a PAT with jwt_required — a PAT cannot mint another PAT.
• Everything else on the control plane accepts either. A PAT with the right scopes can do anything a session can, subject to the publish rule above.
• The PAT has to be in the BRAINBASE_TOKEN environment variable for control-plane commands. A PAT saved on disk by token create is not read by agent, orchestration, link, unlink, sync, status or team. See Authentication.