Skip to main content
Auth0 provides a built-in enrollment and authentication flow using Universal Login. However, if you want to create your own user interface, you can use the MFA API to accomplish it.

​
Prerequisites

Before you can use the MFA APIs, you’ll need to enable the MFA grant type for your application. Go to Auth0 Dashboard > Applications > Advanced Settings > Grant Types and select MFA.

​
Enroll with OTP

​
Get MFA token

Depending on when you are triggering enrollment, you can obtain an for using the MFA API in different ways:

​
Enroll authenticator

Make a POST request to the MFA Associate endpoint to enroll the user’s authenticator. The bearer token required by this endpoint is the MFA token obtained in the previous step. To enroll with OTP, set the authenticator_types parameter to [otp]. If successful, you receive a response like this: 
{
  "authenticator_type": "otp",
  "secret": "EN...S",
  "barcode_uri": "otpauth://totp/tenant:user?secret=...&issuer=tenant&algorithm=SHA1&digits=6&period=30",
  "recovery_codes": [ "N3B...XC"]
}
If you get a User is already enrolled error, the user already has an MFA factor enrolled. Before associating another factor with the user, you must challenge the user with the existing factor. If this is the first time the user is associating an authenticator, you’ll notice the response includes recovery_codes. Recovery codes are used to access the user’s account in the event that they lose access to the account or device used for their second-factor authentication. These are one-time usable codes, and new ones are generated as necessary.

​
Confirm OTP enrollment

To confirm the enrollment, the end user will need to enter the secret obtained in the previous step in an OTP generator application like Google Authenticator. They can enter the secret by scanning a QR code with the barcode_uri or by typing the secret code manually in that OTP application. You should provide users a way to get the secret as text in case they cannot scan the QR code (for example, if they are enrolling from a mobile device, or using a desktop OTP application). After the user enters the secret, the OTP application will display a 6-digit code, that the user should enter in your application. The application should then make a POST request to the , including that otp value. If the call was successful, you’ll receive a response in the following format, containing the access token: 
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
At this point, the authenticator is fully associated and ready to be used, and you have the authentication tokens for the user. You can check at any point to verify whether an authenticator has been confirmed by calling the MFA Authenticators endpoint. If the authenticator is confirmed, the value returned for active is true.

​
Challenge with OTP

​
Get MFA token

Get an MFA token following the steps described in Authenticate With Resource Owner Password Grant and MFA.

​
Retrieve enrolled authenticators

You can list all enrolled authenticators using the MFA Authenticators endpoint: You will get a list of authenticators with the following format: 
[
    {
        "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "totp|dev_6NWz8awwC8brh2dN",
        "authenticator_type": "otp",
        "active": true
    }
]

​
Complete authentication using received code

The user will collect a one time password, which you will then collect from them. You can verify the code and get authentication tokens using the OAuth0 Token endpoint, specifying the one time password in the otp parameter: If the call was successful, you’ll receive a response in the format below, containing the access token: 
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}

​
Customize MFA

Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s release stages, read Product Release Stages. To participate in the early access, contact Auth0 Support.
Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application. During authentication at the oauth/token endpoint, the response returns the mfa_required error that includes the mfa_token to use the MFA API and the mfa_requirements parameter with a list of authenticators: 
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
Use the mfa_token to call the mfa/authenticator endpoint for a list of all factors the user has enrolled and match the same type your application supports. You also need to obtain the matching authenticator_type to issue challenges: 
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
Enforce the MFA challenge by calling the request/mfa/challenge endpoint. Further customize your MFA flow with Auth0 Actions. To learn more, read Actions Triggers: post-challenge - API Object.

​
Learn more