Using App passwords

App passwords are single purpose access tokens with reduced user access (specified at the time of creation). These passwords can be useful for scripting, CI/CD tools, and testing Bitbucket connected applications while they are in development.

To authenticate with Bitbucket Cloud using an App password, you will need the App password and the user’s Bitbucket username (not the email address used for logging into Bitbucket and other Atlassian products). Your Bitbucket username is listed under Bitbucket profile settings on your Bitbucket Personal settings page.

The following examples show how to use Bitbucket Cloud App passwords with the Git command line interface (Git CLI) and Bitbucket Cloud REST APIs.

Using App passwords with the Git command line interface

We recommend connecting to Bitbucket Cloud using SSH keys when interacting with the Git command line interface. App passwords should be used with Git in programs and scripts that are non-interactive, such as build tools and CI/CD applications. For details on setting up SSH keys for Bitbucket, see: Set up SSH keys for Bitbucket Cloud.

To use a Bitbucket Cloud App password with the Git CLI, create an App password with the following permissions:

  • Repository Read (repository)

  • Repository Write (repository:write)

You have two options for using an App password with the Git CLI: provide the App password through an interact prompt, or include the App password in the URL.

App passwords through the interactive password prompt

This method avoids storing the App password insecurely in the URL and requires the App password to be entered every time Git interacts with Bitbucket Cloud (commands such as git pull, git push, and git fetch). You will also need your Bitbucket username. Your Bitbucket username is listed under Bitbucket profile settings on your Bitbucket Personal settings page.

To provide the App password though an interactive prompt, clone the repository with the following command:

1 git clone https://{bitbucket_username}@bitbucket.org/{workspace}/{repository}.git

For repositories already cloned to the local device, update the remote URL with the following command:

1 git remote set-url origin https://{bitbucket_username}@bitbucket.org/{workspace}/{repository}.git

Include the App password in the URL

We recommend not storing the App password insecurely as plain-text or permanently as part of the git remote URL. This method is useful if the App password has been stored securely as a 'secret' variable in a build tool.

To use App passwords without an interactive password prompt, you can include the App password in the URL. For example: when cloning the repository, run the following command:

1 git clone https://{bitbucket_username}:{app_password}@bitbucket.org/{workspace}/{repository}.git

For repositories already cloned to the local device, update the remote URL with the following command:

1 git remote set-url origin https://{bitbucket_username}:{app_password}@bitbucket.org/{workspace}/{repository}.git

Using App passwords with a Bitbucket wiki

We recommend connecting to Bitbucket Cloud using SSH keys when interacting with the Git command line interface. App passwords should be used with Git in programs and scripts that are non-interactive, such as build tools and CI/CD applications. For details on setting up SSH keys for Bitbucket, see: Set up SSH keys for Bitbucket Cloud.

To use a Bitbucket Cloud App password with the Bitbucket Wiki with the Git CLI, create an App password with the following permission: Wikis — Read and Write (wiki).

You have two options for using an App password with the Git CLI: provide the App password through an interact prompt, or include the App password in the URL.

App passwords through the interactive password prompt

This method avoids storing the App password insecurely in the URL and requires the App password to be entered every time Git interacts with Bitbucket Cloud (commands such as git pull, git push, and git fetch). You will also need your Bitbucket username. Your Bitbucket username is listed under Bitbucket profile settings on your Bitbucket Personal settings page.

To provide the App password though an interactive prompt, clone the repository with the following command:

1 git clone https://{bitbucket_username}@bitbucket.org/{workspace}/{repository}.git/wiki

For repositories already cloned to the local device, update the remote URL with the following command:

1 git remote set-url origin https://{bitbucket_username}@bitbucket.org/{workspace}/{repository}.git/wiki

Include the App password in the URL

We recommend not storing the App password insecurely as plain-text or permanently as part of the git remote URL. This method is useful if the App password has been stored securely as a 'secret' variable in a build tool.

To use App passwords without an interactive password prompt, you can include the App password in the URL. For example: when cloning the repository, run the following command:

1 git clone https://{bitbucket_username}:{app_password}@bitbucket.org/{workspace}/{repository}.git/wiki

For repositories already cloned to the local device, update the remote URL with the following command:

1 git remote set-url origin https://{bitbucket_username}:{app_password}@bitbucket.org/{work

Using App passwords 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 a Bitbucket Cloud App password 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 the Bitbucket username and an App password. Your Bitbucket username is listed under Bitbucket profile settings on your Bitbucket Personal settings page.

The App password, along with the user’s Bitbucket username, can be sent as login credentials. For example:

1 2 3 4 curl --request POST \ --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repository}/commits' \ --user '{bitbucket_username}:{app_password}' \ --header 'Accept: application/json'

Alternatively, they can be sent in a HTTP Authorization header after the Bitbucket username and App password have been base64 encoded. For example:

1 2 3 4 5 6 my_credentials_after_base64_encoding=`echo -n '{bitbucket_username}:{app_password}' | 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'

 

Additional Help