How can I disable MFA for a locked-out admin user in FusionAuth?
-
An admin user in our FusionAuth instance has MFA enabled but cannot complete the MFA challenge (lost device, cannot receive codes, etc.). This has locked them out of their account. We need to disable MFA for this user to restore access. What options are available to resolve this situation?
-
If an admin user is locked out due to MFA, you have several options:
-
Use Recovery Codes (if available): If the user previously generated recovery codes, they can use one of those codes to complete the MFA challenge and regain access. Once logged in, they can disable or reconfigure MFA.
-
Generate Recovery Codes via API: Another admin with API access can generate recovery codes for the locked-out user using the Generate Recovery Codes API endpoint:
POST /api/user/two-factor/recovery-code/{userId}Replace
{userId}with the locked-out user's ID. This will generate new recovery codes that can be shared with the user to complete their MFA challenge.-
Have Another Admin Disable MFA: If you have another admin user with access to the FusionAuth admin UI, they can navigate to the locked-out user's account and disable MFA directly from the user management interface. Users with the
adminrole can remove MFA methods from any user without requiring a one-time verification code. Navigate to Users → Manage User → Multi-Factor tab, click the red trash can icon next to the MFA method, and confirm the removal. -
Use the User API to Remove MFA: An admin with API access can also remove MFA methods by updating the user object directly. Retrieve the user via the User API, remove the methods from the
twoFactorarray, and thenPUTthe updated user back. Note that you must usePUT(notPATCH) due to how array handling works:
# Retrieve the user curl -XGET -H "Authorization: $API_KEY" \ 'https://your-fusionauth-url/api/user/{userId}' # Remove the twoFactor array entries and PUT the user back curl -XPUT -H 'Content-type: application/json' \ -H "Authorization: $API_KEY" \ 'https://your-fusionauth-url/api/user/{userId}' \ -d '{user object with twoFactor array cleared}'Important Note: The standard Disable Multi-Factor API (
DELETE /api/user/two-factor/{userId}) is not suitable for this situation, as it requires a valid verification code or recovery code from the user to complete the request. This API is designed for users who can still authenticate.These approaches allow you to restore access without losing the security benefits of MFA for other users.
Related Documentation
- Multi-Factor Authentication (MFA) - Disable MFA on a User
- Generate Recovery Codes API
- Retrieve Recovery Codes API
- Recovery Codes Overview
- Disable Multi-Factor API (requires verification code - not suitable for locked-out users)
- The mfa_deleter Role (for support teams with restricted permissions)
- User Support Guide - Remove an MFA Method
-
-
D dan has marked this topic as solved