Addon
Branch restrictions
Branching model
Commit statuses
Commits
Deployments
Downloads
Issue tracker
Pipelines
Projects
Pullrequests
Refs
Reports
Repositories
Snippets
Source
Ssh
Users
Webhooks
Workspaces
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.



OAuth 2.0

Our OAuth 2 implementation is merged in with our existing OAuth 1 in such a way that existing OAuth 1 consumers automatically become valid OAuth 2 clients. The only thing you need to do is edit your existing consumer and configure a callback URL.

Once that is in place, you'll have the following 2 URLs:

1
2
https://bitbucket.org/site/oauth2/authorize
https://bitbucket.org/site/oauth2/access_token

For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens. Note that Resource Owner Password Credentials Grant (4.3) is no longer supported.

1. Authorization Code Grant (4.1)

The full-blown 3-LO flow. Request authorization from the end user by sending their browser to:

1
2
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code

The callback includes the ?code={} query parameter that you can swap for an access token:

1
2
$ curl -X POST -u "client_id:secret" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=authorization_code -d code={code}

2. Implicit Grant (4.2)

This flow is useful for browser-based add-ons that operate without server-side backends.

Request the end user for authorization by directing the browser to:

1
2
https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token

That will redirect to your preconfigured callback URL with a fragment containing the access token (#access_token={token}&token_type=bearer) where your page's js can pull it out of the URL.

3. Client Credentials Grant (4.4)

Somewhat like our existing "2-LO" flow for OAuth 1. Obtain an access token that represents not an end user, but the owner of the client/consumer:

1
2
$ curl -X POST -u "client_id:secret" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=client_credentials

4. Bitbucket Cloud JWT Grant (urn:bitbucket:oauth2:jwt)

If your Atlassian Connect add-on uses JWT authentication, you can swap a JWT for an OAuth access token. The resulting access token represents the account for which the add-on is installed.

Make sure you send the JWT token in the Authorization request header using the "JWT" scheme (case sensitive). Note that this custom scheme makes this different from HTTP Basic Auth (and so you cannot use "curl -u").

1
2
$ curl -X POST -H "Authorization: JWT {jwt_token}" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=urn:bitbucket:oauth2:jwt

Making Requests

Once you have an access token, as per RFC-6750, you can use it in a request in any of the following ways (in decreasing order of desirability):

  1. Send it in a request header: Authorization: Bearer {access_token}
  2. Include it in a (application/x-www-form-urlencoded) POST body as access_token={access_token}
  3. Put it in the query string of a non-POST: ?access_token={access_token}

Repository Cloning

Since add-ons will not be able to upload their own SSH keys to clone with, access tokens can be used as Basic HTTP Auth credentials to clone securely over HTTPS. This is much like GitHub, yet slightly different:

1
2
$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git

The literal string x-token-auth as a substitute for username is required (note the difference with GitHub where the actual token is in the username field).

Refresh Tokens

Our access tokens expire in one hour. When this happens you'll get 401 responses.

Most access tokens grant responses (Implicit and JWT excluded). Therefore, you should include a refresh token that can then be used to generate a new access token, without the need for end user participation:

1
2
$ curl -X POST -u "client_id:secret" \
  https://bitbucket.org/site/oauth2/access_token \
  -d grant_type=refresh_token -d refresh_token={refresh_token}

Scopes

Bitbucket's API applies a number of privilege scopes to endpoints. In order to access an endpoint, a request will need to have the necessary scopes.

Scopes are declared in the descriptor as a list of strings, with each string being the name of a unique scope.

A descriptor lacking the scopes element is implicitly assumed to require all scopes and as a result, Bitbucket will require end users authorizing/installing the add-on to explicitly accept all scopes.

Our best practice suggests you add the scopes your add-on needs, but no more than it needs.

Invalid scope strings will cause the descriptor to be rejected and the installation to fail.

The available scopes are:

project

Provides the repository scope permission for every repository under a project or projects.

project:write

This scope is deprecated, and has been made obsolete by project:admin. Please see the deprecation notice here.

project:admin

Provides admin access to a project or projects. No distinction is made between public and private projects. This scope doesn't implicitly grant the project scope or the repository:write scope on any repositories under the project. It gives access to the admin features of a project only, not direct access to its repositories' contents.

  • ability to create the project
  • ability to update the project
  • ability to delete the project

repository

Provides read access to a repository or repositories. Note that this scope does not give access to a repository's pull requests.

  • access to the repo's source code
  • clone over HTTPS
  • access the file browsing API
  • download zip archives of the repo's contents
  • the ability to view and use the issue tracker on any repo (created issues, comment, vote, etc)
  • the ability to view and use the wiki on any repo (create/edit pages)

repository:write

Provides write (not admin) access to a repository or repositories. No distinction is made between public and private repositories. This scope implicitly grants the repository scope, which does not need to be requested separately. This scope alone does not give access to the pull requests API.

  • push access over HTTPS
  • fork repos

repository:admin

Provides admin access to a repository or repositories. No distinction is made between public and private repositories. This scope doesn't implicitly grant the repository or the repository:write scopes. It gives access to the admin features of a repo only, not direct access to its contents. This scope can be used or misused to grant read access to other users, who can then clone the repo, but users that need to read and write source code would also request explicit read or write. This scope comes with access to the following functionality:

  • view and manipulate committer mappings
  • list and edit deploy keys
  • ability to delete the repo
  • view and edit repo permissions
  • view and edit branch permissions
  • import and export the issue tracker
  • enable and disable the issue tracker
  • list and edit issue tracker version, milestones and components
  • enable and disable the wiki
  • list and edit default reviewers
  • list and edit repo links (Jira/Bamboo/Custom)
  • list and edit the repository webhooks
  • initiate a repo ownership transfer

repository:delete

Provides access to delete a repository or repositories.

pullrequest

Provides read access to pull requests. This scope implies the repository scope, giving read access to the pull request's destination repository.

  • see and list pull requests
  • create and resolve tasks
  • comment on pull requests

pullrequest:write

Implicitly grants the pullrequest scope and adds the ability to create, merge and decline pull requests. This scope also implicitly grants the repository:write scope, giving write access to the pull request's destination repository. This is necessary to allow merging.

  • merge pull requests
  • decline pull requests
  • create pull requests
  • approve pull requests

issue

Ability to interact with issue trackers the way non-repo members can. This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.

  • view, list and search issues
  • create new issues
  • comment on issues
  • watch issues
  • vote for issues

issue:write

This scope implicitly grants the issue scope and adds the ability to transition and delete issues. This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.

  • transition issues
  • delete issues

wiki

Provides access to wikis. This scope provides both read and write access (wikis are always editable by anyone with access to them). This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.

  • view wikis
  • create pages
  • edit pages
  • push to wikis
  • clone wikis

webhook

Gives access to webhooks. This scope is required for any webhook-related operation.

This scope gives read access to existing webhook subscriptions on all resources the authorization mechanism can access, without needing further scopes. For example:

  • A client can list all existing webhook subscriptions on a repository. The repository scope is not required.
  • Existing webhook subscriptions for the issue tracker on a repo can be retrieved without the issue scope. All that is required is the webhook scope.

To create webhooks, the client will need read access to the resource. Such as: for issue:created, the client will need to have both the webhook and the issue scope.

  • list webhook subscriptions on any accessible repository, user, team, or snippet
  • create/update/delete webhook subscriptions.

snippet

Provides read access to snippets. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication).

  • view any snippet
  • create snippet comments

snippet:write

Provides write access to snippets. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication). This scope implicitly grants the snippet scope which does not need to be requested separately.

  • create snippets
  • edit snippets
  • delete snippets

email

Ability to see the user's primary email address. This should make it easier to use Bitbucket Cloud as a login provider for apps or external applications.

account

Ability to see all the user's account information. Note that this doesn't include any ability to change any of the data.

  • see all email addresses
  • language
  • location
  • website
  • full name
  • SSH keys
  • user groups

account:write

Ability to change properties on the user's account.

  • delete the authorizing user's account
  • manage the user's groups
  • change a user's email addresses
  • change username, display name and avatar

pipeline

Gives read-only access to pipelines, steps, deployment environments and variables.

pipeline:write

Gives write access to pipelines. This scope allows a user to:

  • Stop pipelines
  • Rerun failed pipelines
  • Resume halted pipelines
  • Trigger manual pipelines.

This scope is not needed to trigger a build using a push. Performing a git push (or equivalent actions) will trigger the build. The token doing the push only needs the repository:write scope.

This doesn't give write access to create variables.

pipeline:variable

Gives write access to create variables in pipelines at the various levels:

  • Workspace
  • Repository
  • Deployment

runner

Gives read-only access to pipelines runners setup against a workspace or repository.

runner:write

Gives write access to create/edit/disable/delete pipelines runners setup against a workspace or repository.

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.

Repository Access Tokens

Repository Access Tokens are passwords (or tokens) that provide access to a single repository. These tokens can authenticate with Bitbucket APIs for scripting, CI/CD tools, Bitbucket Cloud-connected apps, and Bitbucket Cloud integrations. The level of access provided by the token is set when a repository admin creates it, by setting permission scopes. Repository Access Tokens are linked to their repository, not a user or a workspace, preventing them from being used to access any other repositories or workspaces.

When using Bitbucket APIs with a Repository Access Token, the token will be treated as the "user" in the Bitbucket UI and Bitbucket logs. This includes using the Repository 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 Access Token as a user. This user uses the Repository Access Token name and a custom icon to differentiate it from a regular user in the UI.

For details on creating, managing, and using Repository Access Tokens, visit Repository Access Tokens.

Considerations for using Repository Access Tokens

  • After creation, a Repository Access Token can't be viewed or modified. The token's name, created date, last accessed date, and scopes are visible on the Repository Access Token page.
  • Repository Access Tokens can only be granted a limited set of Bitbucket's permission scopes.
  • Provided you set the correct permission scopes, you can use a Repository Access Token to clone (repository) and push (repository:write) code to the token's corresponding repository.
  • You can't use a Repository Access Token to log into the Bitbucket website.
  • Repository Access Tokens don't require two-step verification.
  • You can set permission scopes (specific access rights) for each Repository Access Token.
  • You can't use a Repository Access Token to manipulate or query repository permissions.
  • Repository Access Tokens will not be listed in any repository or workspace permission API response.
  • Repository Access Tokens are deactivated when a repository is transferred or deleted.
  • Any content created by the Repository Access Token will persist after the Repository Access Token has been revoked.

Available permissions scopes

The available scopes for Repository Access Tokens are:

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

App passwords

App passwords allow users to make API calls to their Bitbucket account through apps such as Sourcetree.

Some important points about app passwords:

  • You cannot view an app password or adjust permissions after you create the app password. Because app passwords are encrypted on our database and cannot be viewed by anyone. They are essentially designed to be disposable. If you need to change the scopes or lost the password just create a new one.

  • You cannot use them to log into your Bitbucket account.

  • You cannot use app passwords to manage team actions.

    App passwords are tied to an individual account's credentials and should not be shared. If you're sharing your app password you're essentially giving direct, authenticated, access to everything that password has been scoped to do with the Bitbucket API's.

  • You can use them for API call authentication, even if you don't have two-step verification enabled.

  • You can set permission scopes (specific access rights) for each app password.

Create an app password