Branch restrictions
Branching model
Commit statuses
Issue tracker
Other operations

Rate this page:

Authentication methods

The purpose of this section is to describe how to authenticate when making API calls using the Bitbucket REST API.

Basic auth

Basic HTTP Authentication as per RFC-2617 (Digest not supported). Note that Basic Auth is available only with username and app password as credentials.

Access Tokens

Access Tokens are passwords (or tokens) that provide access to a single repository, project or workspace. These tokens can authenticate with Bitbucket APIs for scripting, CI/CD tools, Bitbucket Cloud-connected apps, and Bitbucket Cloud integrations.

Access Tokens are linked to a repository, project, or workspace, not a user account. The level of access provided by the token is set when a repository, or workspace admin creates it, by setting permission scopes.

There are three types of Access Token:

  • Repository Access Tokens can connect to a single repository, preventing them from accessing any other repositories or workspaces.
  • Project Access Tokens can connect to a single project, providing access to any repositories within the project.
  • Workspace Access Tokens can connect to a single workspace and have access to any projects and repositories within that workspace.

When using Bitbucket APIs with an Access Token, the token will be treated as the "user" in the Bitbucket UI and Bitbucket logs. This includes when using the Access Token to leave a comment on a pull request, push a commit, or merge a pull request. The Bitbucket UI and API responses will show the Repository/Project/Workspace Access Token as a user. The username shown in the Bitbucket UI is the Access Token name, and a custom icon is used to differentiate it from a regular user in the UI.

Considerations for using Access Tokens

  • After creation, an Access Token can't be viewed or modified. The token's name, created date, last accessed date, and scopes are visible on the repository, project, or workspace Access Tokens page.
  • Access Tokens can access a limited set of Bitbucket's permission scopes.
  • Provided you set the correct permission scopes, you can use an Access Token to clone (repository) and push (repository:write) code to the token's repository or the repositories the token can access.
  • You can't use an Access Token to log into the Bitbucket website.
  • Access Tokens don't require two-step verification.
  • You can set permission scopes (specific access rights) for each Access Token.
  • You can't use an Access Token to manipulate or query repository, project, or workspace permissions.
  • Access Tokens are not listed in any repository or workspace permission API response.
  • Access Tokens are deactivated when deleting the resource tied to it (a repository, project, or workspace). Repository Access Tokens are also revoked when transferring the repository to another workspace.
  • Any content created by the Access Token will persist after the Access Token has been revoked.
  • Access Tokens can interact with branch restriction APIs, but the token can't be configured as a user with merge access when using branch restrictions.

There are some APIs which are inaccessible for Access Tokens, these are:

Repository Access Tokens