Using access tokens for a project
Access tokens for a project are a premium feature. To learn about the Bitbucket Cloud Premium plan, visit: Bitbucket Cloud Premium.
Access tokens for a project 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. Access tokens for a project are connected to a project, not a user, and are managed by the project admins.
The following examples show how to use Bitbucket Cloud access tokens for a project with Bitbucket Cloud REST APIs and the Git command line interface (Git CLI).
Using access tokens for a project 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 access token for a project 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 Project Access Token as a bearer token in an HTTP Authorization header. For example:
curl --request GET \
--url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}' \
--header 'Authorization: Bearer <project_access_token>' \
--header 'Accept: application/json'Using access tokens for a project with the Git command-line interface
Access tokens for a project 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 an access token for the project 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 access token for a project with the Git CLI, create an access token in the project with the following permissions:
Repository Read (
repository)Repository Write (
repository:write)
You have two options for using an access token for a project with the Git CLI: provide the access token through an interact prompt, or include the access token in the URL.
Access tokens for a project through the interactive password prompt
This method avoids storing the access token for a project insecurely in the URL. It requires the access token for the project 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 access token for the project through an interactive prompt:
Clone the repository with the following command:
git 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:
git remote set-url origin https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
cd {repository}/Set the git user for the repository, such as:
git config user.email "{bot_email}"Where
{bot_email}is the access token for the project email generated when you created the access token (for example,52c16467c5f19101ff2061cc@bots.bitbucket.org).
The access token for a project email:
Is not the name of the project-level access token.
Can be retrieved from the project’s 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 access token for a project in the URL
We recommend not storing the access token for a project insecurely as plain text or permanently as part of the git remote URL. This method is helpful if the access token has been stored securely as a 'secret' variable in a build tool.
To use access tokens for a project without an interactive password prompt, you can include the access token in the URL. For example:
Clone the repository with the following command:
git clone https://x-token-auth:{project_access_token}@bitbucket.org/{workspace}/{repository}.gitFor repositories already cloned to the local device, update the remote URL with the following command:
git remote set-url origin https://x-token-auth:{project_access_token}@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
git remote set-url origin https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitSet the git user for the repository, such as:
git config user.email "{botid}@bots.bitbucket.org"Where
{botid}is the access token id generated when you created the access token for the project. The access token id is not the project-level access token’s name.
Was this helpful?