Skip to main content
You can use the Auth0 MFA API to complete the authentication flow using the Resource Owner Password Flow (sometimes called Password Grant or ROPG) when is enabled.

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

​
Authenticate user

When you use the Resource Owner Password Flow to authenticate, you call the /oauth/token endpoint with the user’s username and password. When MFA is enabled, the response includes an mfa_required error and a mfa_token.
The default expiry time of access tokens with the https://{yourDomain}/mfa/* audience is 10 minutes. This value cannot be configured.
{
    "error": "mfa_required",
    "error_description": "Multifactor authentication required",
    "mfa_token": "Fe26...Ha"
}

​
Retrieve enrolled authenticators

After getting the error above, you need to find out if the user has an MFA factor enrolled or not. Call the MFA Authenticators endpoint, using the MFA token obtained in the previous section. You will get an array with the available authenticators. The array will be empty if the user did not enroll a factor. 
[
    {
        "id": "recovery-code|dev_O4KYL4FtcLAVRsCl",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "email|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "email",
        "name": "email@address.com"
    }
]

​
Enroll MFA factor

If the user is not enrolled in MFA, use the MFA token obtained earlier and enroll it using the MFA Associate endpoint. See the following links to implement this flow based on the authentication factor:

​
Challenge user with MFA

If the user is already enrolled in MFA, you need to challenge the user with one of the existing factors. Use the authenticator_id return by the MFA Authenticators endpoint when calling the MFA Challenge endpoint. After the challenge is complete, call /oauth/token endpoint again to finalize the authentication flow and get the authentication tokens. See the links below to implement this flow depending on the authentication factor:

​
MFA OTP code limitations and restrictions

Expiry time: The expiry time of MFA OTP codes is 5 minutes. This value is not configurable. Code validation: After a user validates an MFA OTP code, it cannot be used again. Code validation rate limiting: Unsuccessful user validation attempts are rate limited using a bucket algorithm. The bucket starts with 10 attempts and refreshes at a rate of 1 attempt per 6 minutes.

​
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.
Customize your MFA flows with the MFA API. With the MFA API, you can allow your users to enroll and challenge with a specific choice of factors your application supports. When MFA is enabled with the Resource Owner Password Flow to authenticate, call to the /oauth/token endpoint to request an access token. The authorization server returns an mfa_required error which provides:
  • The mfa_token you need to call the MFA API for enrollment and challenges.
  • The mfa_requirements parameter, which provides the type of factor your application supports for challenges.
{
  "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" }
    ]
  }
}
Use the mfa_token to call the mfa/authenticator endpoint to list 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