Endpoint
POST /mfa/challenge
The Multi-factor Authentication (MFA) API endpoints allow you to enforce MFA when users interact with the Token endpoints, as well as enroll and manage user authenticators.
First, request a challenge based on the challenge types supported by the application and user. If you know that one-time password (OTP) is supported, you can skip the challenge request.
Next, verify the multi-factor authentication using the /oauth/token endpoint and the specified challenge type: a one-time password (OTP), a recovery code, or an out-of-band (OOB) challenge.
To learn more, read:
- Multi-factor Authentication and Resource Owner Password
- Multi-factor Authentication API
- Multi-factor Authentication in Auth0
Challenge Request
Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the application and user. Thechallenge_type is how the user will get the challenge and prove possession. Supported challenge types include:
otp: for one-time password (OTP)oob: for SMS/Voice messages or out-of-band (OOB)
Remarks
- This endpoint does not support enrollment; the user must be enrolled with the preferred method before requesting a challenge.
- Auth0 chooses the challenge type based on the application’s supported types and types the user is enrolled with.
- An
unsupported_challenge_typeerror is returned if your application does not support any of the challenge types the user has enrolled with. - An
unsupported_challenge_typeerror is returned if the user is not enrolled. - If the user is not enrolled, you will get an
association_requirederror, indicating the user needs to enroll to use MFA. Read Add an authenticator below on how to proceed.
Learn More
- Authenticate With Resource Owner Password Grant and MFA
- Manage Authenticator Factors using the MFA API
Body Parameters
The token received from mfa_required error.
Your application’s Client ID.
Your application’s Client Secret.
A whitespace-separated list of challenge types accepted by your application.Allowed values:
oob, otpA JWT containing a signed assertion with your application credentials.
The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
The ID of the authenticator to challenge.
Response Schema
Response Messages
| Status | Description |
|---|---|
| 200 | Challenge request successful |
| 400 | Invalid request, such as unsupported challenge type or missing enrollment. |