API tokens are single-purpose, user-based tokens which can be created with limited permissions (or scopes). The following types of permissions are available for API tokens:

• Repositories

• Pull requests

• Projects

• Workspaces

• User data

• Pipelines

• Runners

• Issues

• Webhooks

• Snippets

• SSH keys

• GPG keys

• Permissions

Repositories

Repository permissions provide access to view or modify the user’s Bitbucket Cloud repositories. Bitbucket Cloud allows the following repository permission levels:

• Read

• Write

• Admin

• Delete

Read

Equivalent to read:repository:bitbucket API scope

Allows viewing of repository data. Note that this scope does not give access to a repository's pull requests.

• access to the repository's source code

• access the file browsing API

• access to certain repository configurations such as branching model, default reviewers, etc.

Write

Equivalent to write:repository:bitbucket API scope

Provides access to modify all the repositories the user has access to change, including the source code. This does not include pull requests. No distinction is made between public and private repositories. This scope does not imply the read:repository:bitbucket scope, so you need to request that separately, if required.

Admin

Equivalent to admin:repository:bitbucket API scope

Allows admin activities on repositories. No distinction is made between public and private repositories. This scope does not implicitly grant access to the read:repository:bitbucket or the write:repository:bitbucket scopes. It gives access to the admin features of a repository only, not direct access to its contents. This scope comes with access to the following functionality:

• create repository

• view repository permissions

• view and edit branch restrictions

• edit branching model settings

• edit default reviewers

• view and edit inheritance state for repository settings

Delete

Equivalent to delete:repository:bitbucket API scope

Allows the deletion of repositories data.

Pull requests

Pull request permissions provide access to view or modify Bitbucket Cloud pull requests accessible by the user. Bitbucket Cloud allows the following pull request permission levels:

• Read

• Write

Read

Equivalent to read:pullrequest:bitbucket API scope

Allows viewing of pull requests, plus the ability to comment on pull requests.

This scope does not imply the read:repository:bitbucket scope. With this scope, you could retrieve some data specific to the source/destination repositories of a pull request using pull request endpoints, but it does not give access to repository API endpoints.

Write

Equivalent to write:pullrequest:bitbucket API scope

Allows the ability to create, update, approve, decline, and merge pull requests. This scope does not imply the write:repository:bitbucket scope.

Projects

Project permissions provide access to view or modify the user’s Bitbucket Cloud Projects. Bitbucket Cloud allows the following project permission levels:

• Read

• Admin

Read

Equivalent to read:project:bitbucket API scope

Allows viewing of project and project permission data.

Admin

Equivalent to admin:project:bitbucket API scope

Allows the ability to create, update, and delete a project. No distinction is made between public and private projects. This scope does not implicitly grant access to the read:project:bitbucket scope or any repository scopes. It gives access to the admin features of a project only, not direct access to its repositories' contents.

Workspaces

Workspace permissions provide access to view or modify the user’s Bitbucket Cloud Projects. Bitbucket Cloud allows the following workspace permission levels:

Read

Equivalent to read:workspace:bitbucket API scope

Allows viewing of workspace and workspace permission data.

Admin

Equivalent to admin:workspace:bitbucket API scope

Allows the ability to create, update and delete the workspace. This scope does not implicitly grant access to the read:workspace:bitbucket scope or any repository scopes. It gives access to the admin features of a workspace only, not direct access to its workspaces' contents.

User

User permissions provide access to view or modify the current user’s data. The current user refers to the user making the API request. Bitbucket Cloud allows the following user permission levels:

• Read

• Write

Read

Equivalent to read:user:bitbucket API scope

Allows viewing of data related to the current user.

Write

Equivalent to write:user:bitbucket API scope

Allows the ability to update data related to the current user. This scope does not imply the read:user:bitbucket scope. 

Pipelines

Pipelines permissions provide access to view or control Bitbucket Pipelines for repositories that are accessible by the user. Bitbucket Cloud allows the following pipeline permission levels:

• Read

• Write

• Admin

Read

Equivalent to read:pipeline:bitbucket API scope

Allows read access to all pipeline information (pipelines, steps, caches, artifacts, logs, tests, and code-insights).

Write

Equivalent to write:pipeline:bitbucket API scope

Allows running pipelines (i.e., start/stop/create pipeline) and uploading tests/code-insights. This scope does not imply the read:pipeline:bitbucket scope.

Admin

Equivalent to admin:pipeline:bitbucket API scope

Allows admin activities, such as creating pipeline variables. This scope does not implicitly grant access to the read:pipeline:bitbucket or the write:pipeline:bitbucket scopes.

Runners

Runners permissions provide access to view or modify Bitbucket Pipelines Runners for a Workspace and its repositories. Bitbucket Cloud allows the following pipeline runner permission levels:

• Read

• Write

Read

Equivalent to read:runner:bitbucket API scope

Allows viewing of Bitbucket Pipelines runners information.

Write

Equivalent to write:runner:bitbucket API scope

Allows Bitbucket Pipelines runners management. This scope does not imply the read:runners:bitbucket scope.

Issues

Issues permissions provide access to view or modify Bitbucket Cloud repository issues accessible by the user. Bitbucket Cloud allows the following issue permission levels:

• Read

• Write

• Delete

Read

Equivalent to read:issue:bitbucket API scope

Allows the viewing of Bitbucket Cloud repository issues.

Write

Equivalent to write:issue:bitbucket API scope

Allows the ability to create and update Bitbucket Cloud repository issues. This scope does not implicitly grant access to the read:issue:bitbucket scope.

Delete

Equivalent to delete:issue:bitbucket API scope

Allows the deletion of Bitbucket Cloud repository issues.

Webhooks

The Webhooks permission provides access to view all existing webhooks that are accessible to the user, and provides write access for creating webhooks when combined with other permissions. For details, see: Bitbucket Cloud REST APIs — Webhooks.

• Read

• Write

• Delete

Read

Equivalent to read:webhook:bitbucket API scope

Allows read access to webhooks information.

Write

Equivalent to write:webhook:bitbucket API scope

Allows the ability to create and update webhooks. This scope does not implicitly grant access to the read:webhook:bitbucket scope.

Delete

Equivalent to delete:webhook:bitbucket API scope

Allows the deletion of webhooks.

Snippets

Snippets permissions provide access to view or modify Bitbucket Cloud code snippets in Workspaces that are accessible by the user. Bitbucket Cloud allows the following snippet permission levels:

• Read

• Write

• Delete

Read

Equivalent to read:snippet:bitbucket API scope

Allows the viewing of snippets.

Write

Equivalent to write:snippet:bitbucket API scope

Allows the ability to create and update snippets. This scope does not implicitly grant access to the read:snippet:bitbucket scope.

Delete

Equivalent to delete:snippet:bitbucket API scope

Allows the deletion of snippets.

SSH keys

SSH key permissions provide access to view or modify Bitbucket Cloud SSH keys and deploy keys that are accessible by the user. Bitbucket Cloud allows the following SSH key permission levels:

• Read

• Write

• Delete

Read

Equivalent to read:ssh-key:bitbucket API scope

Allows read access to information related to deploy keys and SSH keys.

Write

Equivalent to write:ssh-key:bitbucket API scope

Allows the ability to create and update deploy keys and SSH keys. This scope does not implicitly grant access to the read:ssh-key:bitbucket scope.

Delete

Equivalent to delete:ssh-key:bitbucket API scope

Allows the deletion of deploy keys and SSH keys. 

GPG keys

GPG key permissions provide access to view or modify Bitbucket Cloud GPG keys that are accessible by the user. Bitbucket Cloud allows the following GPG key permission levels:

• Read

• Write

• Delete

Read

Equivalent to read:gpg-key:bitbucket API scope

Allows read access to information related to GPG keys.

Write

Equivalent to write:gpg-key:bitbucket API scope

Allows the ability to create and update GPG keys. This scope does not implicitly grant access to the read:gpg-key:bitbucket scope.

Delete

Equivalent to delete:gpg-key:bitbucket API scope

Allows the deletion of GPG keys.

Permissions

Permissions provide access to view or modify Bitbucket Cloud permission data that are accessible by the user. Bitbucket Cloud allows the following permission levels:

• Read

• Write

• Delete

Read

Equivalent to read:permission:bitbucket API scope

Allows read access to permissions data.

Write

Equivalent to write:permission:bitbucket API scope

Allows the ability to create and modify permissions related data. This scope does not implicitly grant access to the read:permission:bitbucket scope.

Delete

Allows the deletion of permissions related data.