Skip to content
Novaz AuthenticatorGET

Bitbucket 2FA: how to set up an authenticator app

By the Novaz team · Updated October 29, 2026
Novaz steps checked against version 1.0.5

On this page
  1. Before you start: SSH and a password
  2. Turn on 2FA with an authenticator app
  3. Six recovery codes
  4. If Bitbucket rejects your code
  5. Moving to a new phone
  6. If you lose your authenticator
  7. Turning 2FA off
  8. Official Bitbucket and Atlassian help

Bitbucket Cloud, Atlassian's Git hosting at bitbucket.org, signs you in with an Atlassian account (Bitbucket), but its two-step verification is a separate setting. Atlassian describes two checks, one for the account and one for Bitbucket. With both on, you may face two code prompts in a row, and a code from one won't pass the other (Atlassian).

Bitbucket's own setting, covered here, takes a time-based (TOTP) authenticator app or a FIDO U2F security key. Its help page doesn't mention text messages (Bitbucket). It's optional, unless a Bitbucket Premium workspace requires it before you can reach its private repositories (Bitbucket). For the account layer, see Atlassian's two-step verification help.

The steps use Authenticator App - Novaz on iPhone; other authenticator apps work along the same lines.

How we checked this guide: the Bitbucket steps come from Atlassian's own Bitbucket Cloud help pages, knowledge base articles and developer changelog, linked below, which we read on October 20, 2026. We haven't tested them on a Bitbucket account, so a label may differ slightly. The Novaz steps are checked against the app, version 1.0.5.

Before you start: SSH and a password

Bitbucket lists these requirements (Bitbucket):

  • An SSH key on your account. With two-step verification on, Git's remote actions are expected to go over SSH, so switch your remotes, Git clients and build tools first.
  • A confirmed email address and an Atlassian account password. No password yet? Bitbucket says to set one through password recovery, then log in again.

The two-step page still suggests app passwords for HTTPS and the API, but Bitbucket's changelog scheduled their full deprecation for July 28, 2026 (Bitbucket). Their replacement, API tokens, doesn't require two-step verification (Bitbucket).

Turn on 2FA with an authenticator app

  1. In Bitbucket, select the Settings cog, then Personal Bitbucket settings (Bitbucket).
  2. Under Security, select Two-step verification. The direct address is bitbucket.org/account/settings/two-step-verification/manage (Bitbucket).
  3. Check the requirements, enter your Atlassian account password and select Set up two-step verification.
  4. When the QR code appears, tap + in Novaz, choose Scan QR code and point the camera at it. On the same iPhone, screenshot it and use Choose a photo instead. See scanning a QR code on the same iPhone.
  5. If scanning fails, Bitbucket's Account and Key fields hold the same details. In Novaz, tap +, then Enter key manually, type Bitbucket under Service, and paste the Key into Setup key. See What is a 2FA setup key?
  6. Type the current Novaz code into Verification code.
  7. Download or write down your recovery codes.

Codes have 6 digits (Bitbucket), but no page gives the interval, and a typed key always makes 30-second codes in Novaz, so scan if you can. After that, every login asks for a code in Verification code, then Verify. Bitbucket doesn't mention remembering a device.

Six recovery codes

You get 6 recovery codes, each good once, typed into Verification code like an app code. Keep at least two unused: Bitbucket wants that many to make new codes or to turn two-step verification off. Show recovery codes on the Two-step verification page displays them; once all 6 are used, select Can't find codes? there (Bitbucket).

If you lose the iPhone and have no Novaz backup, or only one from before you added Bitbucket, these codes are your way back in. Store them away from the phone. More in 2FA backup codes.

If Bitbucket rejects your code

Bitbucket's help suggests these checks (Bitbucket, Bitbucket):

  • Type the digits as one string, with no space.
  • Read the right entry. With Atlassian account verification on too, you'll have two, and they aren't interchangeable.
  • Don't reuse a recovery code.
  • Fix the clock: 30 to 60 seconds of drift breaks codes. On iPhone, turn on Settings > General > Date & Time > Set Automatically, or toggle it off and on if it's already on, then wait for a new code. Novaz raises a warning once the clock drifts 15 seconds or more.

Still stuck? Use a recovery code, and see Authenticator code not working?

Moving to a new phone

Bitbucket's way is to switch two-step verification off and on again (Bitbucket). While the old phone works, open Two-step verification, enter its code or a recovery code, select Disable two-step verification, then set it up with the new phone and save the new codes.

In Novaz, an iCloud backup or a backup file restores your accounts on the new iPhone, so the codes keep working without this. Without one, each account goes onto the new iPhone from scratch. See How to transfer your authenticator app to a new iPhone.

If you lose your authenticator

Start with a recovery code. Bitbucket also mentions fetching them over SSH, without giving steps.

With no codes left, a March 2026 knowledge base article describes recovery by email (Atlassian):

  1. At the code prompt, select Forgot code, then Send recovery email. The main help page calls this Can't find codes?, so labels may differ.
  2. The first email just says to wait. 24 hours later, a second one brings a one-time login link (check spam).
  3. The link expires after 24 hours and logs you in with two-step verification off. Set it up again.

The wait can't be shortened: "Atlassian cannot disable two-step verification for any Bitbucket user account" (Bitbucket). If email fails, the article suggests an Atlassian support ticket.

If your Atlassian account has two-step verification too, clear that layer first with its 24-character emergency recovery key. More in Lost the phone with your authenticator app?

Turning 2FA off

In Two-step verification, enter an app or recovery code, select Disable two-step verification, and confirm with Disable (Bitbucket). If you require two-step verification on content you manage, clear Require two-step verification under Access controls first (Bitbucket). Afterwards, delete the Bitbucket entry from Novaz with Remove account.

Official Bitbucket and Atlassian help

More guides: Developer tools