FusionAuth
    • Home
    • Categories
    • Recent
    • Popular
    • Pricing
    • Contact us
    • Docs
    • Login

    How can I disable MFA for a locked-out admin user in FusionAuth?

    Scheduled Pinned Locked Moved Solved
    Frequently Asked Questions (FAQ)
    mfa two-factor api recovery-codes admin
    1
    2
    13
    Loading More Posts
    • Oldest to Newest
    • Newest to Oldest
    • Most Votes
    Reply
    • Reply as topic
    Log in to reply
    This topic has been deleted. Only users with topic management privileges can see it.
    • F
      FASupportBot
      last edited by

      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 you are looking for professional support and not just bot-provided support, please check out https://fusionauth.io/pricing and pick a plan that fits your needs.

      1 Reply Last reply Reply Quote 0
      • F
        FASupportBot
        last edited by

        If an admin user is locked out due to MFA, you have several options:

        1. 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.

        2. 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.

        1. 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 admin role 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.

        2. 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 twoFactor array, and then PUT the updated user back. Note that you must use PUT (not PATCH) 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

        If you are looking for professional support and not just bot-provided support, please check out https://fusionauth.io/pricing and pick a plan that fits your needs.

        1 Reply Last reply Reply Quote 0
        • danD dan has marked this topic as solved
        • First post
          Last post