Using API tokens | Bitbucket Cloud

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.API tokens used to access Bitbucket APIs or perform Git commands must have scopes.Using API tokens with Git commandsTo authenticate with Bitbucket Cloud using an API token, you will need the API token and your Bitbucket username. Your Bitbucket username is listed under Bitbucket profile settings on your Bitbucket Account settings page. Important: Bitbucket usernames using in Git commands with API tokens are case sensitive and must match exactly what appears on your account’s Settings page.API token scopes required for cloning include read:repository:bitbucket. Cloning and pushing require both read:repository:bitbucket and write:repository:bitbucket.API tokens through the interactive password promptThis 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).Be sure to enter your API token when prompted for your password.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 the static username x-bitbucket-api-token-auth or x-token-auth as seen in the examples below. The static username provides more options for git interactions, particularly to simplify interacting with git in apps and integrations.git clone https://x-bitbucket-api-token-auth@bitbucket.org/{workspace}/{repository}.gitgit clone https://x-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}@bitbucket.org/{workspace}/{repository}.gitInclude the API token in the URLWe 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 static usernames x-bitbucket-api-token-auth or x-token-auth:git clone https://x-bitbucket-api-token-auth:{api_token}@bitbucket.org/{workspace}/{repository}.gitgit clone https://x-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 APIsIf 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'Using Bearer authenticationBitbucket also supports Bearer authentication. In addition to Basic auth, you can use a Bearer authorization header as shown below.curl --request POST \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}/commits' \ --header "Authorization: Bearer {api_token}" \ --header 'Accept: application/json'Bearer authentication removes the need to provide the Atlassian email tied to the API token.