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

• Basic auth
• Access Tokens
  • Repository Access Tokens
  • Project Access Tokens
  • Workspace Access Tokens
• App passwords
• OAuth 2.0
  • Making requests
  • Repository cloning
  • Refresh tokens
• Bitbucket OAuth 2.0 Scopes
• Forge App Scopes

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