Using API tokens
API tokens are single purpose access tokens with scoped user access (specified at the time of creation). These tokens can be useful for scripting, CI/CD tools, and testing Bitbucket Connect applications while they are in development.
To authenticate with Bitbucket Cloud using an API token, you will need the API token and your Atlassian account email (used for logging into Bitbucket and other Atlassian products). Your Atlassian account email is listed under Email aliases on your Bitbucket Personal settings page.
The following examples show how to use Bitbucket Cloud API tokens with the Git command line interface (Git CLI) and Bitbucket Cloud REST APIs.
API tokens through the interactive password prompt
This method avoids storing the API token insecurely in the URL and requires the token to be entered every time Git interacts with Bitbucket Cloud (commands such as git pull, git push, and git fetch).
To provide the API token though an interactive prompt, clone the repository with the following command:
git clone https://{bitbucket_username}@bitbucket.org/{workspace}/{repository}.gitAlternatively, you can also use a static user name:
git clone https://x-bitbucket-api-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://{bitbucket_username}@bitbucket.org/{workspace}/{repository}.gitInclude the API token in the URL
We recommend not storing the API token insecurely as plain-text or permanently as part of the git remote URL. This method is useful if the API token has been stored securely as a 'secret' variable in a build tool.
To use API tokens without an interactive password prompt, you can include the API token in the URL. For example, when cloning the repository, run the following command:
git clone https://{bitbucket_username}:{api_token}@bitbucket.org/{workspace}/{repository}.gitAlternatively, you can also use a static user name:
git clone https://x-bitbucket-api-token-auth:{api_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://{bitbucket_username}:{api_token}@bitbucket.org/{workspace}/{repository}.gitUsing API tokens with Bitbucket APIs
If you are building an integration or app for Bitbucket Cloud, we recommend using OAuth where possible. For information on building a Bitbucket Cloud integration or app, visit Atlassian Developer - Bitbucket Cloud.
The following examples show how to use an API token with the curl command as a guide for how to authenticate with Bitbucket Cloud APIs. Both examples are querying the commits on a Bitbucket repository using the List commits API. You will need both your Atlassian account email and an API token. Your Atlassian account email is listed under Email Aliases on your Bitbucket Personal settings page.
The API token, along with the user’s Atlassian account email, can be sent as login credentials. For example:
curl --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}/commits' \
--user '{atlassian_account_email}:{api_token}' \
--header 'Accept: application/json'Alternatively, they can be sent in a HTTP Authorization header after the Bitbucket email and API token have been base64 encoded. For example:
my_credentials_after_base64_encoding=`echo -n '{atlassian_account_email}:{api_token}' | base64`
curl --request POST \
--url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}/commits' \
--header "Authorization: Basic $my_credentials_after_base64_encoding" \
--header 'Accept: application/json'
Was this helpful?