Manage two-step verification for your Atlassian account

Two-step verification protects your Atlassian account by requiring a second login step. This way your account remains secure, even if your password is compromised.

Set up two-step verification

Before you start

The second login step for two-step verification requires a 6-digit verification code from an authentication app. We support most authentication apps—some of the more common ones are Google Authenticator, Authy, and Duo.

An authentication app on a mobile device is the most popular but not the only solution that provides time-based one-time password (TOTP) authentication. There are also other ways like browser extensions or hardware devices.

You don’t need an Internet connection to set up two-step verification. Air-gapped instances can also adopt this mechanism.

Set up two-step verification

1. Make sure your authentication app is ready to use.

2. Log in to your Atlassian account. Go to User profile, then select Two-step verification.

3. Under Two-step verification settings, select Unlock settings and enter your password to verify your identity.

4. In the Authentication app tab, select Set up and follow the instructions on your screen.

Log in with two-step verification

Once you've enabled two-step verification, you'll need your authentication app to log in every time:

1. Enter your username and password as you would normally.

2. Open your authentication app and retrieve the 6-digit verification code.

3. Enter the verification code, the select Log in.

Recover your account

If you can't access your authentication app to log in with a verification code, recover your Atlassian account using the emergency recovery key you created during the setup.

Use your emergency recovery key instead of a verification code

To recover your account:

1. Enter your username and password as you would normally.

2. When asked for a verification code, select Can't use your mobile device? instead.

3. Enter your emergency recovery key, then select Log in.

4. You'll receive a new emergency recovery key, since you can only use an emergency recovery key once. Copy, print, or write down your new emergency recovery key.

Create a new emergency recovery key

If you've lost your emergency recovery key or you’re concerned that someone else might have access to it, you can create a new emergency recovery key—but only if you’re still logged in. When you create a new emergency recovery key, it will replace the old one.

To create a new emergency recovery key:

1. Log in to your Atlassian account. Go to User profile, then select Two-step verification.

2. Under Two-step verification settings, select Unlock settings and enter your verification code to verify your identity. This step won’t be necessary if you recently verified your identity.

3. In the Authentication app tab, select Manage, then Create new recovery key, then follow the instructions on your screen.

Make sure to copy, print, or write down your new emergency recovery key.

Change your authentication app

We support only one authentication app connection at once. When you connect your account to a new authentication app, we’ll disable the previous one.

To change your authentication app:

1. Log in to your Atlassian account. Go to User profile, then select Two-step verification.

2. Under Two-step verification settings, select Unlock settings and enter your verification code to verify your identity. This step won’t be necessary if you recently verified your identity.

3. In the Authentication app tab, select Manage, then Change authentication app, then follow the instructions on your screen.

Disable two-step verification

If you disable two-step verification, your account will no longer be protected with a second login step.

1. Log in to your Atlassian account. Go to User profile, then select Two-step verification.
2. Under Two-step verification settings, select Unlock settings and enter your verification code to verify your identity. This step won’t be necessary if you recently verified your identity.
3. In the Authentication app tab, select Manage, then Disable, then confirm your choice.

After you disable two-step verification, you’ll no longer log in with an authentication app. You can re-enable two-step verification at any time.

Enforce two-step verification

Two-step verification enforcement is disabled by default. You can enable it using the JVM runtime property -Datlassian.authentication.2sv.enforcement.enabled=true.

Once you enable enforcement, high-risk authority users that have the privileges of user creation, like admins (for Confluence) and system admins (for other Data Center products), will be enforced to set up two-step verification the next time they log in.

Once enforcement is enabled

If you're an admin and enforcement is enabled on your product instance, you may be required to set up two-step verification when you next log in. If that’s the case, you’ll get an email from your admin informing you that two-step verification is required. You'll then need to enable two-step verification as described in the Enable two-step verification section.

When you run Jira in recovery mode, the login form won't accept recovery admin credentials if two-step verification is enabled.

Legacy login form

The login form using the two-step verification capability is enabled by default, but if you have any issues in your environment, you can revert to the legacy login form.

To enable the legacy login form, use the JVM flag -Datlassian.authentication.legacy.mode=true.

If you have any issues with the login form using the two-step verification capability, make sure to report it.

Rate-limiting protection

Rate limiting is applied to the services that verify the time-based one-time password (TOTP) and recovery code during login as well as the TOTP, recovery code, and password verification during session elevation.

Each time a failed request is made (the user entering an incorrect code), the user is blocked from making a subsequent request for a backoff period. Until that period is over, all verification requests made are rate-limited and not processed further.When a request is made after the backoff period is over, it’ll proceed as normal and the provided code will be validated. If the code is found to be incorrect, the backoff period value will be doubled. All requests made before the backoff period is over will be rejected directly with an HTTP 429 error.

This period of time for which the user is blocked from making requests also increases with each failed attempt. This value starts with one second and is doubled with every attempt made with an incorrect TOTP code and recovery code (or password only in case of elevation). This means the value will keep on increasing exponentially from one second to two seconds to four seconds to eight seconds and so on until it reaches 3600 seconds (60 minutes).

By default, rate limiting is applied after the first consecutive failed attempt. In other words, the user will be blocked for one second after making two invalid attempts in a row. This will then double to two seconds when the third failed attempt is made and the user can't make verification attempts in the next two seconds.

If the provided code is correct, the backoff period value will be reset to one second.

The number of tolerated failed attempts can be customized by the atlassian.authentication.2sv.rate.limit.tolerated.failures.count system property.

Back up and restore

When you back up and restore your instance, make sure the backup is complete and includes the database and application [shared] home directory.

Incomplete restoration may result in a corrupted instance state and two-step verification malfunction in runtime due to missing data required for secure processing. Authentication to the instance may be blocked until the missing data is restored.

Recovery unenrollment

In case a user has lost their recovery key, you can use a special REST endpoint to disable two-step verification for that user. The endpoint is accessible for system admins only via the REST API to provide an unenrollment option when a user can’t disable two-step verification on their own. Due to security reasons, it requires the system admin to have the two-step verification set up with TOTP.

As a system admin, you can’t disable two-step verification via the REST API for yourself.

Basic authentication

To make your instance secure, we advise to disable basic authentication on your instance since two-step verification doesn’t protect this method. Learn how to disable basic authentication

In case your integration requires basic authentication enabled, you can still disable basic authentication in general and prepare an allowlist for exceptional cases. Learn how to create an allowlist when basic authentication is disabled