Enable two-step verification

Two-step verification secures your account by requiring a second confirmation, in addition to your password, to access Bitbucket Cloud. That second step means your account stays secure even if your password is compromised.

To enable two-step verification you will need the following:

• An authentication app for your mobile device like Authy.

• A confirmed email address and password for your Atlassian Account.

• An SSH key associated with your account.

Once you have two-step verification enabled, you'll enter the verification code provided by your authentication application to log into your Bitbucket account. As an alternative form of two-step verification, you can link a security key device, such as a YubiKey, to your account so that you don't need to enter a code when logging in.

Prepare for two-step verification

Before you enable two-step verification make sure you've met the following requirements:

Add SSH to your account and update repositories.

Bitbucket's two-step verification requires the use of SSH to interact with your repositories remotely. This means you'll need to do more than just add an SSH key to your account, you'll need to use SSH for cloning, pushing, pulling, fetching, and all other remote actions with your repository.

Follow the instructions in Set up an SSH key to set up SSH for your system.

Confirm applications use SSH or an app password

You will need to confirm that applications, like Git clients and automated build and deploy tools, use either SSH or an application password to access Bitbucket. Refer to your application's documentation for instructions on setting up and confirming SSH access.

Some applications might use SSH for most actions but might use Bitbucket's API over HTTPS for some actions. For more information, see Troubleshooting two-step verification.

Install a verification app for your mobile device

You'll need to install an application (such as Authy, Google Authenticator, or Duo for iOS and Android, or Microsoft Authenticator for Windows mobile) on your mobile device or desktop. You can select any application which supports the Time-based One-time Password Algorithm (TOTP) method. Once you have the application installed the easiest method to set up the application is to scan a QR code with your mobile device.

After you install the application, make sure that your device has the correct time. Otherwise, the verification codes you receive may not work when you enter them into Bitbucket.

Created with Sketch.

Enable two-step verification

Once you have met or verified the requirements, you can log into your Bitbucket account and enable two-step verification.

To enable two-step verification:

1. Select the Settings cog in the upper-right corner > select Personal Bitbucket settings.

2. Click Two-step verification under Security.

3. Review the requirements and make sure you've fulfilled them all.

4. Enter your Atlassian Account password and click Set up two-step verification.
   If your Atlassian account does not have a password, you'll need to set one in order to set up two-step verification. You can set a password for your Atlassian account using password recovery. Once you've set a password, log in to Bitbucket again and proceed.

5. Scan the QR code using your mobile devices and enter the resulting code in the Verification code field.
   If your mobile device cannot successfully scan the code, you can use the information in the Account and Key fields to connect your application. See the instructions for your authentication application to complete the process.

6. Download or otherwise record your recovery codes and keep them in a secure place where you can access them.

You're all set up! The next time you log into Bitbucket you'll need to use a verification code to access your account.

Add security keys

Security keys are hardware devices that you can use as your two-step verification. Instead of typing a verification code every time you sign in, you insert the security key and press a button on the device.

Bitbucket supports security keys that use the FIDO U2F standard. These keys only work with a recent version of Google Chrome, which means that you need to install or update your browser if you want to begin using a security key.

To add a security key:

1. Select the Settings cog in the upper-right corner > select Personal Bitbucket settings.

2. Click Two-step verification under Security.

3. Under Security keys, enter a name for your device in the text box.

4. Click Add security key.

5. Insert your security key and press its button.

6. The next screen explains that you need to authenticate to finish adding your security key. Press the button on your device one more time.

Done! Next time you log in, all you have to do is insert the security key and press it. No more getting out your mobile device!

After you have two-step verification set up with a security key, your page looks similar to this one:

1. Recovery codes: Click to reveal and save these codes in case you need them in the future.

2. Disable two-step: Click to remove two-step verification from your account.

3. Security keys: After you enter a name and click the button, insert your key to add it.

Use two-step verification

To access your account after you've enabled two-step verification, you'll need your mobile device (or a security key device if you've linked one to your account).

To access your account with a verification code:

1. Log in as you normally would log in.

2. Open your verification app and retrieve a new code.

3. Enter the code in the Verification code field and click Verify.

Here's a few things you can check if you run into trouble:

• Did you enter the code with a space? Some apps display the code in two sections and usually you enter a single set of numbers without spaces.

• Did your app generate more than one set of codes? Many apps display all the latest codes if you use it for more than one account. Make sure you're entering the code for Bitbucket.

• Are you using a recovery code? If so, make sure it's not one you've used before. Recovery codes are only good once.

To access your account with a security key device:

1. Log in to Bitbucket using your Atlassian Account.

2. Insert your security key.

3. Press the button on your security key.

Here's a few things you can check if you run into trouble:

• Is you security key not working? Refresh the page and try again.

• Are you using a browser other than Google Chrome? Switch to Google Chrome and then try again.

• Using Google Chrome but still getting an error message? Check to make sure you're on the latest version.

Replace a device

When you get a new mobile device you'll have to remove the old device and add the new device by completing the following procedure:

1. Select the Settings cog in the upper-right corner > select Personal Bitbucket settings.

2. Click Two-step verification under Security.

3. Provide either a code from your old device or a recovery code, if prompted.

4. Click Disable two-step verification.

5. Scan the QR code using your mobile device and enter the resulting code in the Verification code field.
   
   

   • If your mobile device cannot successfully scan the code, you can use the information in the Account and Key fields to connect your application. See the instructions for your authentication application to complete the process.

   • Download or otherwise record your recovery codes and keep them in a secure place where you can access them.

Your new device is all set up! The next time you log into Bitbucket you'll need to use a verification code to access your account.

Recovery codes

If you don't have your mobile device or security key, you can access your account using a recovery code. When you first set up two-step verification, we gave you recovery codes and told you put them somewhere safe in case you need them. To access your recovery codes, select Show recovery codes on the Two-step verification page in Bitbucket.

Enter a recovery code in place of your verification code

Recovery codes work exactly the same as regular verification codes. Just choose one (remember you can only use it once) and enter it into the Verification code field. After you succeed in accessing your account, delete the recovery code you used from your list to avoid using it again.

Getting more recovery codes

If you have used all 6 recovery codes, select the Can’t find codes? button at the bottom of the Two-step verification > Recover codes modal.

Disable two-step verification

You'll need at least one verification or recovery code to disable two-step verification. If you have to log into Bitbucket first, you'll need at least two verification or recovery codes.

To disable two-step verification:

1. Select the Settings cog in the upper-right corner > select Personal Bitbucket settings.

2. Click Two-step verification under Security.

3. Enter a verification code from your authentication app or a recovery code and you'll see your two-step verification settings.

4. Click Disable two-step verification and then click Disable in the confirmation message. 

You've disabled two-step verification. You can enable two-step verification again at any time.

Troubleshooting two-step verification

Debug common problems that might result from using two-step verification.

Unable to log in but I know I'm using the right code

• Some authentication apps display the verification code you need in two segments like this: 111 000. However, you generally want to enter your code as a single string: 111000.

• Check to verify you are looking at both the correct authentication app and the correct account and code. Many apps let you house several accounts and codes in the same app and some display in the same area.

• Try using a recovery code to log in. If that still doesn't work, try retrieving recovery codes through SSH (if you have access to a system with your SSH key) and use one of those codes, or click on Can't find codes? at the bottom of the Two-step verification > Recovery codes modal.

• Verify that the device with the installed verification application has the correct time. If not, reset the clock, and then try to access your Bitbucket account again.

Application passwords

Some applications that rely on basic authentication may no longer work as expected. While Bitbucket recommends that third-party application developers switch to using OAuth, there are still many applications where https may be the only option. Application-specific passwords allow you to create a password for apps such as Sourcetree and Bamboo so that you can use Git and the API over HTTPS as needed.

First, check that your application is set to use SSH for authentication with Bitbucket. If you need to use the Bitbucket API over HTTPS, use application passwords.