How to recover or reset 2FA Authentication in Jira
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
As mentioned in the official documentation for "Manage two-step verification", it is possible to disable the two-step authentication verification for an user if the access to the app and/or the recovery code are lost and the user is locked out of the application.
This KB aims to add more details to the process of removing, recovering and ensuring that the user regain the application access.
ℹ️ Manage two-step verification for your Atlassian account - Recovery unenrollment
Solution
REST API
As mentioned in the official doc:
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.
Before you reset - prerequisites
Verify the requestor's identity through your organisation's standard account-recovery process — not via the locked-out user's email alone.
Confirm the admin performing the reset has Jira System Admin permission — both the API and DB methods require it.
Record the action in your internal audit log: date, time, admin who performed the reset, user reset, and reason.
Notify the user that their 2FA was reset by an admin, so they can re-enrol immediately and report any account anomalies.
Failure to follow these prerequisites turns this recovery procedure into a social-engineering vector
Choose the right method
The user has their recovery code → They can self-serve via the "Manage two-step verification" documentation. No admin action needed.
The user is locked out and a system admin is available to perform the reset → Use the REST API method (preferred — least invasive, no DB access required).
The REST API method fails or is unavailable in your Jira version → Use the database method (last resort — requires DB access and carries unsupported-operation risk).
Using cURL to disable the 2FA verification for a specific user:
Example cURL:
curl --request DELETE \
--url 'http://{baserURL}/rest/tsv/1.0/totp/unenroll/user/{username}>' \
--header 'Authorization: Bearer <api_token>' \
--header 'Content-Type: application/json' \
--data '{"totpCode":"<totp_code>"}'⚠️ The 6-digit "<totp_code>" needs to be manually generated in admin's authenticator app, added to the curl parameters and used within the 30 seconds timeout of the authenticator app.
✅ A 204 status response indicates the success without any response message from the server.
Database
The steps outlined in this article are provided AS-IS. This means we've had reports of them working for some customers, under certain circumstances, yet they are not officially supported, nor can we guarantee they'll work for your specific scenario.
You may follow through and validate them on your own non-prod environments prior to production, or fall back to supported alternatives if they don't work out.
We also invite you to contact our Community for matters that are outside Atlassian's scope of support!
Alternatively, it's also possible to query the recovery code for the affected user in the database, allowing the user to regain its access using the recovery features in the UI:
Query to get the user's RECOVERY CODE
SELECT totp."RECOVERY_CODE", au.lower_user_name, totp."USER_KEY"
FROM "AO_ED669C_TOTP_USER_ENROLLMENT" totp
JOIN app_user au ON au.user_key = totp."USER_KEY"
WHERE "USER_KEY" = (
SELECT user_key
FROM app_user
WHERE lower_user_name = LOWER('<username>')
);ℹ️ Follow the official documentation to learn how to use the recovery code to regain the user access in order to register a new app authentication or to turn off the 2FA settings in the UI.
⚠️ Important notice ⚠️
Manipulating the database directly is not supported by Atlassian! Proceed at your own risk!
Remove the affected user's 2FA settings:
It's also possible to remove the user's 2FA credentials and parameters entry in the database, effectively, disabling the two-step authentication settings of that user:
Warning: Backup your database before proceeding.
Before running any SQL in this article, create a full backup of your Jira database. This is a database-level operation with no undo other than restoring from backup. Only proceed if you're comfortable running SQL directly against the Jira database, and test on a staging or cloned environment first, wherever possible.
Query to delete the user's 2FA parameters
DELETE FROM "AO_ED669C_TOTP_USER_ENROLLMENT"
WHERE "USER_KEY" = (
SELECT "user_key"
FROM "app_user"
WHERE "lower_user_name" = LOWER('<username>')
);Verify the reset was successful
Ask the user to log in with username and password only — they should not be prompted for a TOTP code.
Confirm the user can re-enrol in 2FA immediately via their profile settings (Profile → Two-step verification).
Review the Jira audit log for the unenrolment event timestamp to confirm the action was recorded.
Optionally, run the following SELECT to confirm the user's enrollment record has been removed (applies to both the REST API and DB methods):
SELECT * FROM "AO_ED669C_TOTP_USER_ENROLLMENT" WHERE "USER_KEY" = ( SELECT user_key FROM app_user WHERE lower_user_name = LOWER('<username>') );A result with no rows confirms the 2FA enrollment has been successfully removed.
Scope — when to use this KB
This KB applies when:
The user has 2FA enabled via Jira's built-in TOTP two-step verification system.
This KB does NOT apply when:
2FA is enforced by an external identity provider (Okta, Azure AD, Atlassian Guard, etc.) — the reset must be performed in the IdP, not in Jira.
The user is using a hardware security key (WebAuthn / FIDO2) — see the WebAuthn KB for the applicable procedure.
You need to disable 2FA globally for the instance — see the instance-level 2FA configuration KB, not this user-level recovery article.
Related Articles
Manage two-step verification for your Atlassian account — self-serve 2FA management for users with their recovery code
Was this helpful?