Token Scopes

When you authenticate with an API token, you pick the scopes it grants. The tables below map command workflows to scopes; some commands read a resource before changing it. API-token write scopes do not include read scopes, and scopes do not override account permissions or repository restrictions. See the Bitbucket scope reference. Generate tokens at Bitbucket API tokens.

Scope reference

Bitbucket Cloud API token scopes follow the format <action>:<resource>:bitbucket. The CLI uses these scopes:

Scope	Grants
`read:user:bitbucket`	Read user profiles; verifies any login, resolves your UUID for `bb pr list --author/--reviewer/--mine`, `bb pr status` and the `bb ssh-key` / `bb gpg-key` commands, and user lookups
`read:repository:bitbucket`	List and view repositories, their files, downloads, commits, and commit build statuses; search code
`write:repository:bitbucket`	Upload and delete downloads
`admin:repository:bitbucket`	Create repositories; add and remove default reviewers; list, view, create, and delete branch restrictions
`delete:repository:bitbucket`	Delete repositories
`read:pullrequest:bitbucket`	List, view, and diff pull requests; read comments, activity, checks, reviewers, and default reviewers
`write:pullrequest:bitbucket`	Create, edit, approve, unapprove, request changes, decline, merge, and mark pull requests ready; add/remove reviewers; add, edit, and delete comments
`read:pipeline:bitbucket`	List and view pipelines and their steps, read step logs; list and view deployments and environments
`write:pipeline:bitbucket`	Trigger and stop pipelines
`read:workspace:bitbucket`	List and view workspaces
`read:project:bitbucket`	List and view projects
`admin:project:bitbucket`	Create projects
`read:snippet:bitbucket`	List and view snippets, read snippet comments
`write:snippet:bitbucket`	Create and edit snippets; watch and unwatch; add, edit, and delete snippet comments
`delete:snippet:bitbucket`	Delete snippets
`read:webhook:bitbucket`	List and view webhooks
`write:webhook:bitbucket`	Create webhooks
`delete:webhook:bitbucket`	Delete webhooks
`read:ssh-key:bitbucket`	List SSH keys on your account
`write:ssh-key:bitbucket`	Add SSH keys
`delete:ssh-key:bitbucket`	Delete SSH keys
`read:gpg-key:bitbucket`	List GPG keys on your account
`write:gpg-key:bitbucket`	Add GPG keys
`delete:gpg-key:bitbucket`	Delete GPG keys

Command → scope map

Auth (`bb auth …`)

Command	Required scopes
`bb auth login`	`read:user:bitbucket` (verifies the credentials)
`bb auth logout`	(none; local-only for API tokens; OAuth revoke uses the existing token)
`bb auth status`	`read:user:bitbucket`
`bb auth token`	(none; prints the locally-stored token)

Repositories (`bb repo …`)

Command	Required scopes
`bb repo list`	`read:repository:bitbucket`
`bb repo view`	`read:repository:bitbucket`
`bb repo create`	`admin:repository:bitbucket`
`bb repo delete`	`delete:repository:bitbucket`
`bb repo default-reviewers list`	`read:pullrequest:bitbucket`
`bb repo default-reviewers add`	`admin:repository:bitbucket`, `read:user:bitbucket`
`bb repo default-reviewers remove`	`admin:repository:bitbucket`, `read:user:bitbucket`
`bb repo cat`	`read:repository:bitbucket`
`bb repo ls`	`read:repository:bitbucket`
`bb repo downloads list`	`read:repository:bitbucket`
`bb repo downloads upload`	`write:repository:bitbucket`
`bb repo downloads delete`	`write:repository:bitbucket`

admin: and delete: are separate scopes. A token with admin:repository:bitbucket can create repositories but cannot delete them.

Default reviewers live under the pull request resource in Bitbucket’s API, which is why reading them needs a pull request scope while changing them needs the repository admin scope. add and remove also resolve the target account via GET /users/{selected_user} first; add read:user:bitbucket for that lookup. See Get a user.

Pull requests (`bb pr …`)

read:pullrequest:bitbucket covers list, status, view, diff, checkout, activity, checks, comments list, comments view and reviewers list.

write:pullrequest:bitbucket covers PR mutations (create, edit, ready, approve, unapprove, request-changes, decline, merge, and reviewer changes). ready and reviewer changes also fetch the PR first, so grant read:pullrequest:bitbucket for those workflows. edit without a PR ID lists open PRs to find the current branch, and create --default-reviewers reads the effective defaults; those paths also need the pull request read scope.

Atlassian currently documents read:pullrequest:bitbucket for comment mutations, including add, edit, reply, resolve, unresolve and delete. A scope named read is therefore not a guarantee that a token cannot change comments. Check the endpoint reference and account permissions before treating a token as read-only.

bb pr status and bb pr list --mine (or --author/--reviewer) also need read:user:bitbucket; they call GET /user (or GET /users/{selected_user}) to resolve the UUID before filtering. So do the commands that take a <user> argument: bb pr create --reviewer, bb pr reviewers add|remove, and bb repo default-reviewers add|remove all resolve an account ID or {uuid} through GET /users/{selected_user} (and @me through GET /user) before making the change. Add read:user:bitbucket to any token that runs those.

bb pr create --reviewer, bb pr reviewers add|remove and bb pr list --author|--reviewer also accept a nickname, display name or email, which they look up through GET /workspaces/{workspace}/members. That needs read:workspace:bitbucket.

bb pr checkout runs git fetch and git checkout locally after reading the pull request, so it uses your normal git credentials too.

No bb pr command needs read:repository:bitbucket. The CLI resolves the workspace and repository from your git remote (or --workspace/--repo), not from the API.

Pipelines (`bb pipeline …`)

Command	Required scopes
`bb pipeline list`	`read:pipeline:bitbucket`
`bb pipeline view`	`read:pipeline:bitbucket`
`bb pipeline logs`	`read:pipeline:bitbucket`
`bb pipeline run`	`read:pipeline:bitbucket`, `write:pipeline:bitbucket`
`bb pipeline stop`	`write:pipeline:bitbucket`

Commits and build statuses (`bb commit …`, `bb status …`)

Command	Required scopes
`bb commit list`	`read:repository:bitbucket`
`bb commit view`	`read:repository:bitbucket`
`bb status list`	`read:repository:bitbucket`
`bb status set`	`read:repository:bitbucket` (as documented by Atlassian; see below)

Atlassian currently lists read:repository:bitbucket for creating and updating build statuses. As with PR comments, a scope named read is not a guarantee against mutations. These tables describe the published API contract; server enforcement has not been tested with live tokens.

Workspaces (`bb workspace …`)

Command	Required scopes
`bb workspace list`	`read:workspace:bitbucket`
`bb workspace view`	`read:workspace:bitbucket`

bb workspace list calls GET /user/workspaces; the entries wrap each workspace in a workspace object. Both that endpoint and GET /workspaces/{workspace} require the workspace read scope in the current API reference. The deprecated GET /workspaces endpoint is not used by the CLI.

Projects (`bb project …`)

Command	Required scopes
`bb project list`	`read:project:bitbucket`
`bb project view`	`read:project:bitbucket`
`bb project create`	`admin:project:bitbucket`

Branch restrictions (`bb branch-restriction …`)

Command	Required scopes
`bb branch-restriction list`	`admin:repository:bitbucket`
`bb branch-restriction view`	`admin:repository:bitbucket`
`bb branch-restriction create`	`admin:repository:bitbucket`
`bb branch-restriction delete`	`admin:repository:bitbucket`

Even reading branch restrictions needs the admin scope. create --user also resolves each user through GET /users/{user}, which needs read:user:bitbucket.

Deployments (`bb deployment …`)

Command	Required scopes
`bb deployment list`	`read:pipeline:bitbucket`
`bb deployment view`	`read:pipeline:bitbucket`
`bb deployment environments`	`read:pipeline:bitbucket`

SSH and GPG keys (`bb ssh-key …`, `bb gpg-key …`)

Command	Required scopes
`bb ssh-key list`	`read:ssh-key:bitbucket`, `read:user:bitbucket`
`bb ssh-key add`	`read:ssh-key:bitbucket`, `write:ssh-key:bitbucket`, `read:user:bitbucket`
`bb ssh-key delete`	`delete:ssh-key:bitbucket`, `read:user:bitbucket`
`bb gpg-key list`	`read:gpg-key:bitbucket`, `read:user:bitbucket`
`bb gpg-key add`	`read:gpg-key:bitbucket`, `write:gpg-key:bitbucket`, `read:user:bitbucket`
`bb gpg-key delete`	`delete:gpg-key:bitbucket`, `read:user:bitbucket`

Every key command calls GET /user first to resolve your account, hence read:user:bitbucket. Bitbucket’s spec lists both the read and write scope for adding a key.

Snippets (`bb snippet …`)

Command	Required scopes
`bb snippet list`	`read:snippet:bitbucket`
`bb snippet view`	`read:snippet:bitbucket`
`bb snippet create`	`read:snippet:bitbucket`, `write:snippet:bitbucket`
`bb snippet edit`	`read:snippet:bitbucket`, `write:snippet:bitbucket`
`bb snippet delete`	`delete:snippet:bitbucket`
`bb snippet watch`	`write:snippet:bitbucket`
`bb snippet unwatch`	`write:snippet:bitbucket`
`bb snippet comments list`	`read:snippet:bitbucket`
`bb snippet comments add`	`read:snippet:bitbucket`, `write:snippet:bitbucket`
`bb snippet comments edit`	`read:snippet:bitbucket`, `write:snippet:bitbucket`
`bb snippet comments delete`	`write:snippet:bitbucket`

delete:snippet:bitbucket is separate from the write scope.

The snippet endpoint reference requires both snippet read and write scopes for adding and editing comments, and write for deleting them.

Search (`bb search …`)

Command	Required scopes
`bb search code`	`read:repository:bitbucket`

A token with the right scope still gets a 404 when code search is not enabled for the workspace. See Search Commands.

Webhooks (`bb webhook …`)

Command	Required scopes
`bb webhook list`	`read:webhook:bitbucket`
`bb webhook view`	`read:webhook:bitbucket`
`bb webhook create`	`read:webhook:bitbucket`, `write:webhook:bitbucket`
`bb webhook delete`	`delete:webhook:bitbucket`

Bitbucket also requires the scope that applies to each event a new webhook subscribes to, for example read:repository:bitbucket for repo:push and read:pullrequest:bitbucket for pullrequest:created. Only workspace owners can create --scope workspace webhooks, whatever the token grants.

Raw API (`bb api`)

bb api needs whatever scope the endpoint you call requires; look the endpoint up in Atlassian’s Bitbucket Cloud API reference. A 403 can indicate missing scopes, insufficient account permissions, or a repository restriction; inspect the response instead of assuming a scope problem.

Local-only commands

These don’t hit the API and don’t need any scope:

bb repo clone (builds the clone URL from workspace and repository names, then shells out to git; uses your normal git credentials)
bb browse (builds the URL from local git context)
bb config (all subcommands)
bb completion
bb (root, including the version-check)

Common profiles

Read-only automation (status checks, dashboards)

read:user:bitbucket
read:repository:bitbucket
read:pullrequest:bitbucket
read:pipeline:bitbucket

Bot account that creates and merges pull requests

read:user:bitbucket
read:pullrequest:bitbucket
write:pullrequest:bitbucket

Add read:repository:bitbucket only if the bot also runs bb repo, bb commit or bb status commands.

Repo provisioning automation

read:user:bitbucket
read:repository:bitbucket
admin:repository:bitbucket
delete:repository:bitbucket

Drop delete:repository:bitbucket unless the automation actually tears repositories down.

CI/CD automation (trigger pipelines, report build statuses)

read:user:bitbucket
read:repository:bitbucket
write:repository:bitbucket
read:pipeline:bitbucket
write:pipeline:bitbucket

CI monitor bot

read:user:bitbucket
read:repository:bitbucket
read:pipeline:bitbucket

Troubleshooting

If a command exits with 2003 API_FORBIDDEN, check the scopes above, account permissions, and repository restrictions. You can’t add scopes to an existing token; mint a new one and re-authenticate:

bb auth logout
printf '%s' "$NEW_TOKEN" | bb auth login -u [email protected] --with-token

--with-token reads the token from stdin, keeping it out of your shell history and out of ps output. -p new-token works too, but writes the secret into both.

Token Scopes

Scope reference

Command → scope map

Auth (bb auth …)

Repositories (bb repo …)

Pull requests (bb pr …)

Pipelines (bb pipeline …)

Commits and build statuses (bb commit …, bb status …)

Workspaces (bb workspace …)

Projects (bb project …)

Branch restrictions (bb branch-restriction …)

Deployments (bb deployment …)

SSH and GPG keys (bb ssh-key …, bb gpg-key …)

Snippets (bb snippet …)

Search (bb search …)

Webhooks (bb webhook …)

Raw API (bb api)