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. 
curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data username=user@example.com \
  --data password=pwd \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data audience=https://someapi.com/api \
  --data 'scope=openid profile read:sample'
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. 
curl --request GET \
  --url 'https://{yourDomain}/mfa/authenticators' \
  --header 'authorization: Bearer MFA_TOKEN' \
  --header 'content-type: application/json'
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.

​
Learn more

⌘I