Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Using Project Access Tokens
Project Access Tokens are a premium feature. To learn about the Bitbucket Cloud Premium plan, visit: Bitbucket Cloud Premium.
Project 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. Project Access Tokens are connected to a project, not a user, and are managed by the project admins.
The following examples show how to use Bitbucket Cloud Project Access Tokens with Bitbucket Cloud REST APIs and the Git command line interface (Git CLI).
Using Project 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 Project 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 Project 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 <project_access_token>' \
--header 'Accept: application/json'Using Project Access Tokens with the Git command line interface
Project 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 Project 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 Project Access Token with the Git CLI, create a Project Access Token with the following permissions:
Repository Read (repository)
Repository Write (repository:write)
You have two options for using a Project Access Token with the Git CLI: provide the Project Access Token through an interact prompt, or include the Project Access Token in the URL.
Project Access Tokens through the interactive password prompt
This method avoids storing the Project Access Token insecurely in the URL. It requires the Project 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 Project 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 Project Access Token email generated when you created the Project Access Token (for example, 52c16467c5f19101ff2061cc@bots.bitbucket.org).
The Project Access Token email:
Is not the Project Access Token name.
Can be retrieved from the Project Access Tokens page on the project 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 Project Access Token in the URL
We recommend not storing the Project Access Token insecurely as plain text or permanently as part of the git remote URL. This method is helpful if the Project Access Token has been stored securely as a 'secret' variable in a build tool.
To use Project Access Tokens without an interactive password prompt, you can include the Project Access Token in the URL. For example:
Clone the repository with the following command:
1git 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:
1git remote set-url origin https://x-token-auth:{project_access_token}@bitbucket.org/{workspace}/{repository}.gitNavigate into the newly cloned repository:
1git remote set-url origin https://x-token-auth@bitbucket.org/{workspace}/{repository}.gitSet the git user for the repository, such as:
1git config user.email "{botid}@bots.bitbucket.org"Where {botid} is the Project Access Token id generated when you created the Project Access Token. The Project Access Token id is not the Project Access Token name.
Was this helpful?
Still need help?
The Atlassian Community is here for you.