Token Scopes

When you authenticate with an API token, you pick the scopes it grants. This page maps every bb command to the minimum scope it needs, so you can mint a token for one workflow and nothing more. 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 --mine`, and covers `bb workspace list`
`read:repository:bitbucket`	List and view repositories, commits, and commit build statuses
`write:repository:bitbucket`	Set commit build statuses
`admin:repository:bitbucket`	Create repositories; add and remove default reviewers
`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, 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
`write:pipeline:bitbucket`	Trigger and stop pipelines
`read:issue:bitbucket`	List and view issues
`write:issue:bitbucket`	Create, edit, comment on, and close issues
`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, edit, and delete snippets; watch and unwatch; add, edit, and delete snippet comments

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`
`bb repo default-reviewers remove`	`admin: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/{user} first — that endpoint carries no scope of its own, but a token that cannot see the account will fail there.

Pull requests (`bb pr …`)

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

write:pullrequest:bitbucket covers create, edit, ready, approve, decline, merge, reviewers add|remove, and the comment mutations (comments add|edit|reply|resolve|unresolve|delete). Bitbucket’s API spec still maps the comment endpoints to the read scope, so a read-only token may be enough for bb pr comments add — grant the write scope anyway, that is the one to rely on.

bb pr list --mine also needs read:user:bitbucket — it calls GET /user to resolve your 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 the handle you pass through GET /users/{selected_user} before making the change. Add read:user:bitbucket to any token that runs those.

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`	`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`	`write:repository:bitbucket`

Issues (`bb issue …`)

Command	Required scopes
`bb issue list`	`read:issue:bitbucket`
`bb issue view`	`read:issue:bitbucket`
`bb issue create`	`write:issue:bitbucket`
`bb issue edit`	`write:issue:bitbucket`
`bb issue close`	`write:issue:bitbucket`
`bb issue comment`	`write:issue:bitbucket`

Workspaces (`bb workspace …`)

Command	Required scopes
`bb workspace list`	`read:workspace:bitbucket`, `read:user:bitbucket`
`bb workspace view`	(none — the endpoint is unscoped)

bb workspace list calls GET /workspaces, which Bitbucket’s API spec scopes to account — the legacy name for read:user:bitbucket. Grant it alongside read:workspace:bitbucket. GET /workspaces/{workspace} carries no scope at all, so bb workspace view works with whatever grant already makes the workspace visible to you.

Projects (`bb project …`)

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

Snippets (`bb snippet …`)

Command	Required scopes
`bb snippet list`	`read:snippet:bitbucket`
`bb snippet view`	`read:snippet:bitbucket`
`bb snippet create`	`write:snippet:bitbucket`
`bb snippet edit`	`write:snippet:bitbucket`
`bb snippet delete`	`write: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`	`write:snippet:bitbucket`
`bb snippet comments edit`	`write:snippet:bitbucket`
`bb snippet comments delete`	`write:snippet:bitbucket`

As with pull request comments, Bitbucket’s API spec maps snippet comment writes to the read scope. Grant write:snippet:bitbucket anyway — that is the scope to rely on.

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 from bb api means the token is missing that endpoint’s scope, not that the path is wrong.

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

Issue triage bot

read:user:bitbucket
read:repository:bitbucket
read:issue:bitbucket
write:issue:bitbucket

Troubleshooting

If a command exits with 2003 API_FORBIDDEN, your token is missing the scope listed above. You can’t add scopes to an existing token — mint a new one and re-authenticate:

bb auth logout
echo "$NEW_TOKEN" | bb auth login -u your-username --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 …)

Issues (bb issue …)

Workspaces (bb workspace …)

Projects (bb project …)

Snippets (bb snippet …)

Raw API (bb api)