Token Scopes

When you authenticate with an API token, you choose which scopes the token grants. This page maps every bb command to the minimum scope required to run it, so you can mint a token with exactly the permissions a workflow needs and nothing more.

Scope Reference

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

Scope	Grants
`read:user:bitbucket`	Read your own user profile (required by `bb auth status`, used to verify any login)
`read:repository:bitbucket`	List and view repositories, commits, and commit build statuses; list default reviewers
`write:repository:bitbucket`	Create repositories, manage default reviewers, set commit build statuses
`admin:repository:bitbucket`	Delete repositories
`read:pullrequest:bitbucket`	List, view, and diff pull requests; read comments, activity, checks, and reviewers
`write:pullrequest:bitbucket`	Create, edit, approve, decline, merge, and mark PRs ready; add/edit/delete comments; add/remove reviewers
`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
`write:snippet:bitbucket`	Create, edit, and delete snippets

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 clone`	`read:repository:bitbucket` (plus your normal git auth)
`bb repo create`	`write:repository:bitbucket`
`bb repo delete`	`admin:repository:bitbucket`
`bb repo default-reviewers list`	`read:repository:bitbucket`
`bb repo default-reviewers add`	`write:repository:bitbucket`
`bb repo default-reviewers remove`	`write:repository:bitbucket`

Pull Requests (`bb pr …`)

Read-only PR commands — list, view, diff, checkout, activity, checks, comments list, reviewers list — only need read:pullrequest:bitbucket (plus read:repository:bitbucket for repository context).

Command	Required scopes
`bb pr list`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr view`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr diff`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr checkout`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr activity`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr checks`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr comments list`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr reviewers list`	`read:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr create`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr edit`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr ready`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr approve`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr decline`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr merge`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr comments add`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr comments edit`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr comments delete`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr reviewers add`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`
`bb pr reviewers remove`	`write:pullrequest:bitbucket`, `read:repository:bitbucket`

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 (`bb commit …`)

Commits are part of the repository resource, so commit commands reuse the repository scopes:

Command	Required scopes
`bb commit list`	`read:repository:bitbucket`
`bb commit view`	`read:repository:bitbucket`

Build Statuses (`bb status …`)

Commit build statuses also live under the repository resource:

Command	Required scopes
`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`
`bb workspace view`	`read:workspace:bitbucket`

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`

Local-only commands

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

bb config (all subcommands)
bb completion
bb (root, including the version-check)

Common Profiles

Pick the profile that matches your workflow and grant only those scopes when creating the token.

Read-only automation (status checks, dashboards)

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

Bot account that creates and merges PRs

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

Repo provisioning automation

read:user:bitbucket
read:repository:bitbucket
write:repository:bitbucket
admin:repository:bitbucket

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 in the table above. Mint a new token with the required scope (you can’t add scopes to an existing token) and re-authenticate:

bb auth logout
bb auth login -u your-username -p new-token

Token Scopes

Scope Reference

Command → Scope Map

Auth (bb auth …)

Repositories (bb repo …)

Pull Requests (bb pr …)

Pipelines (bb pipeline …)

Commits (bb commit …)

Build Statuses (bb status …)

Issues (bb issue …)

Workspaces (bb workspace …)

Projects (bb project …)

Snippets (bb snippet …)