Manage Authentication Factors with Authentication API

Before you start

• Enable the MFA grant type for your application. To learn more, read Update Grant Types.

Auth0 provides several API endpoints to help you manage the authenticators you’re using with an application for multi-factor authentication (MFA). You can use these endpoints to build a complete user interface that lets users manage their authenticator factors.

Get MFA API access tokens

To call the MFA API to manage enrollments, you first need to obtain an access token for the MFA API.

To use the MFA API as part of an authentication flow, you can follow the steps detailed in Authenticate With Resource Owner Password Grant and MFA. If you are building a user interface to manage authentication factors, you’ll need to obtain a token you can use for the MFA API at any moment, not only during authentication.

An MFA access token, or an access token with an https://{yourDomain}/mfa/ audience, simultaneously authenticates and instigates an MFA challenge request. Factor enablement in your tenant and enrollment by your users determine whether the MFA challenge initiates:

• If your tenant allows for multiple factor enrollment and your users enroll in a valid factor (excluding email), such as a one-time password (OTP), the user is issued the MFA challenge upon login.
• If your users are not enrolled with any authentication factors, or are only enrolled with the email factor, the MFA token is minted and the user not issued a challenge.

The default expiry time of access tokens with the https://{yourDomain}/mfa/* audience is 10 minutes. This value cannot be configured.

Universal Login

If you are using Universal Login, redirect to the Authorize endpoint, specifying the https://{yourDomain}/mfa/ audience.

When https://{yourDomain}/mfa/ is specified as the audience, MFA is enforced. When end users enable Remember this browser while .../mfa is specified as audience, the setting will have no effect.

Auth0 recommends that tenant administrators create an action that sets allowRememberBrowser to false. This will hide Remember this browser from view in the end user’s experience.

Resource owner password grant

If you are using the Resource Owner Password Grant (ROPG), you have 3 options:

• Ask for the https://{yourDomain}/mfa/ audience when logging-in, and use a refresh token to refresh it later.
• If you need to list and delete authenticators, ask the user to authenticate again with /oauth/token, specifying the https://{yourDomain}/mfa/ audience. Users will need to complete MFA before being able to list and/or delete authentication factors.
• If you only need to list authenticators, ask the user to authenticate again using /oauth/token with username/password. The endpoint will return an mfa_required error, and an mfa_token you can use to list authenticators. Users will need to provide their password to see their authenticators.

Scopes

When you request a token for the MFA audience, you can request the following scopes:

Scope	Description
enroll	To enroll a new authenticator.
read:authenticators	To list existing authenticators.
remove:authenticators	To delete an authenticator.

List authenticators

To get a list of the authenticators for a user, you can call the MFA Authenticators endpoint:

cURL

curl --request GET \
  --url 'https://{yourDomain}/mfa/authenticators' \
  --header 'authorization: Bearer MFA_TOKEN'

You should receive information about the authenticator type(s) in the response:

[
  {
    "authenticator_type": "recovery-code",
    "id": "recovery-code|dev_IsBj5j3H12VAdOIj",
    "active": true
  },
  {
    "authenticator_type": "otp",
    "id": "totp|dev_nELLU4PFUiTW6iWs",
    "active": true,
  },
  {
    "authenticator_type": "oob",
    "oob_channel": "sms",
    "id": "sms|dev_sEe99pcpN0xp0yOO",
    "name": "+1123XXXXX",
    "active": true
  }
]

For the purposes of building a user interface for end users to manage their factors, you should ignore authenticators that have active as false. Those authenticators are not confirmed by users, so they can’t be used to challenge for MFA.

The MFA API will list the following enrollments depending on the authenticator type:

Authenticator	Actions
Push and OTP	If push is enabled, Auth0 also creates an OTP enrollment. You will see both when listing enrollments.
SMS and Voice	If both SMS and voice are enabled, when a user enrolls with either SMS or voice, Auth0 automatically creates two authenticators for the phone number, one for SMS and another for voice.
Email	All verified emails will be listed as authenticators.

Enroll authenticators

See the following links for details on how to enroll authenticators for different factors:

• SMS or voice
• One-time password (OTP)
• Push
• Email

You can also use the Universal Login flow for enrolling users at any time.

Delete authenticators

To delete an associated authenticator, send a DELETE request to the MFA Authenticators endpoint replacing the AUTHENTICATOR_ID with the relevant authenticator ID. You can get the ID when you list authenticators.

If an mfa_token was used to list authenticators, users will need to complete MFA to obtain an access token with an audience of https://{yourDomain}/mfa/ in order to delete an authenticator.

cURL

curl --request DELETE \
  --url 'https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID' \
  --header 'authorization: Bearer ACCESS_TOKEN'

If the authenticator was deleted, a 204 response is returned.

When you delete an authenticator, the following actions take place depending on the authenticator type:

Authenticator	Action
Push and OTP	When a user enrolls a push authenticator, Auth0 also enrolls OTP. If you delete either of them, the other one will also be deleted.
SMS and Voice	When a user enrolls in either SMS or Voice,. Auth0 creates two authenticators, SMS and voice. If you delete either of them, the other will will also be deleted.
Email	All verified emails listed as authenticators, but you can’t delete them. You can only delete email authenticators that are enrolled explicitly.

Regenerate recovery codes

To delete a recovery code and generate a new one, get an Auth0 Management API access token and use the Management API Recovery Code Regeneration endpoint.

cURL

curl --request POST \
  --url 'https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration' \
  --header 'authorization: Bearer MANAGEMENT_API_TOKEN'

You will get a new recovery code that the end user will need to capture, for example:

{  
   "recovery_code": "FA45S1Z87MYARX9RG6EVMAPE"
}

Learn more

• Enroll and Challenge SMS and Voice Authenticators
• Enroll and Challenge OTP Authenticators
• Enroll and Challenge Push Authenticators
• Enroll and Challenge Email Authenticators
• Challenge with Recovery Codes