When recovery codes are enabled for your tenant, Auth0 automatically generates them when a user enrolls with (MFA). The user should save the recovery code. This code can later be used if the user loses access to the device or account used for MFA. When recovery codes are disabled the MFA API will not return a recovery code when you associate a user’s first MFA factor and users cannot authenticate with a recovery code. You can enable users to authenticate with a recovery code using the MFA API.
  1. Prompt the user for their recovery code. That value should be entered in the application for the user to authenticate.
    Auth0 does not generate recovery codes for DUO and for the legacy google-authenticator factor.
  2. Authenticate with recovery code. Call the OAuth Token endpoint with the recovery code to authenticate and generate a new recovery code. You need to specify the following parameters:
    ParameterValue
    grant_typehttp://auth0.com/oauth/grant-type/mfa-recovery-code
    recovery_codeThe recovery code provided by the user.
    curl --request POST \
--url 'https://{yourDomain}/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=http://auth0.com/oauth/grant-type/mfa-recovery-code \
--data 'client_id={yourClientId}' \
--data 'client_secret={yourClientSecret}' \
--data 'mfa_token={mfaToken}' \
--data 'recovery_code={recoveryCode}'
  3. Prompt user to capture recovery code. If the call is successful, you’ll get the authentication tokens and a new recovery code: 
    {
    "access_token": "O3...H4",
    "id_token": "eyJh...w",
    "scope": "openid profile",
    "expires_in": 86400,
    "recovery_code": "K6LGLV3RSH3VERMKET8L7QKU",
    "token_type": "Bearer"
}
  4. Notify the user that a new recovery code was generated and ask them to capture it.

​
Learn more