Using Access Tokens

Repository Access Tokens are single-purpose access tokens with reduced access (specified during creation). Repository Access Tokens are not tied to a user, but to a repository, and can be managed by the repository’s admins. These tokens can be useful for scripting, CI/CD tools, and testing Bitbucket-connected apps during development.

The following examples show how to use Bitbucket Cloud Repository Access Tokens with Bitbucket Cloud REST APIs and the Git command line interface (Git CLI).

Using Repository Access Tokens with Bitbucket APIs

We recommend Bitbucket Cloud integration or app developers use OAuth for user authentication. For information on creating a Bitbucket Cloud integration or app with OAuth support, visit Atlassian Developer - Bitbucket Cloud.

The following example shows how to use a Bitbucket Cloud Repository Access Token with the curl command as a guide for how to authenticate with Bitbucket Cloud APIs. This example is querying the commits on a Bitbucket repository using the Get Repository API.

To connect to Bitbucket Cloud, send the Repository Access Token as a bearer token in an HTTP Authorization header. For example:

1 2 3 4 curl --request GET \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}' \ --header 'Authorization: Bearer <repository_access_token>' \ --header 'Accept: application/json'

Using Repository Access Tokens with the Git command line interface

Repository Access Tokens should be used with the Git command line interface in programs and scripts that are non-interactive, such as build tools, automation scripts, and CI/CD applications. When using Git directly on a daily basis, we recommend connecting to Bitbucket Cloud using SSH keys or Git Credential Manager to avoid manually entering a Repository Access Token every time you issue a command that interacts with Bitbucket. For details on setting up SSH keys for Bitbucket, see: Set up SSH keys for Bitbucket Cloud.

To use a Bitbucket Cloud Repository Access Token with the Git CLI, create a Repository Access Token with the following permissions:

  • Repository Read (repository)

  • Repository Write (repository:write)

You have two options for using a Repository Access Token with the Git CLI: provide the Repository Access Token through an interact prompt, or include the Repository Access Token in the URL.

Repository Access Tokens through the interactive password prompt

This method avoids storing the Repository Access Token insecurely in the URL. It requires the Repository Access Token to be input every time Git interacts with Bitbucket Cloud (such as git pull, git push, and git fetch). You will also need to configure the git user for the repository.

To provide the Repository Access Token through an interactive prompt:

  1. Clone the repository with the following command:

    1 git clone https://x-token-auth@bitbucket.org/{workspace}/{repository}.git

    For repositories already cloned to the local device, update the remote URL with the following command:

    1 git remote set-url origin https://x-token-auth@bitbucket.org/{workspace}/{repository}.git
  2. Navigate into the newly cloned repository:

    1 cd {repository}/
  3. Set the git user for the repository, such as:

    1 git config user.email "{bot_email}"

    Where {bot_email} is the Repository Access Token email, generated when you created the Repository Access Token (for example 52c16467c5f19101ff2061cc@bots.bitbucket.org).

The Repository Access Token email:

  • is not the Repository Access Token name.

  • can be retrieved from the Repository Access Tokens page on the repository by selecting the name of the Access Token.

  • can’t send or receive emails and is only used for matching Git operations to the Access Token.

Include the Repository Access Token in the URL

We recommend not storing the Repository Access Token insecurely as plain text or permanently as part of the git remote URL. This method is useful if the Repository Access Token has been stored securely as a 'secret' variable in a build tool.

To use Repository Access Tokens without an interactive password prompt, you can include the Repository Access Token in the URL. For example:

  1. Clone the repository with the following command:

    1 git clone https://x-token-auth:{repository_access_token}@bitbucket.org/{workspace}/{repository}.git

    For repositories already cloned to the local device, update the remote URL with the following command:

    1 git remote set-url origin https://x-token-auth:{repository_access_token}@bitbucket.org/{workspace}/{repository}.git
  2. Navigate into the newly cloned repository:

    1 cd {repository}/
  3. Set the git user for the repository, such as:

    1 git config user.email "{botid}@bots.bitbucket.org"

    Where {botid} is the Repository Access Token id, generated when you created the Repository Access Token. The Repository Access Token id is not the Repository Access Token name.



Additional Help