Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Using Repository Access Tokens
Repository Access Tokens are single-purpose access tokens with reduced access (specified during creation) that can be useful for scripting, CI/CD tools, and testing Bitbucket-connected apps during development. Repository Access Tokens are connected to a repository, not a user, and are managed by the repository’s admins.
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 daily, 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:
Clone the repository with the following command:
1git clone https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitFor repositories already cloned to the local device, update the remote URL with the following command:
1git remote set-url origin https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
1cd {repository}/Set the git user for the repository, such as:
1git 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:
Clone the repository with the following command:
1git clone https://x-token-auth:{repository_access_token}@bitbucket.org/{workspace}/{repository}.gitFor repositories already cloned to the local device, update the remote URL with the following command:
1git remote set-url origin https://x-token-auth:{repository_access_token}@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
1cd {repository}/Set the git user for the repository, such as:
1git 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.
Was this helpful?