Multi-factor Authentication API
The Multi-factor Authentication (MFA) API endpoints allow you to enforce MFA when users interact with the Token endpoints, as well enroll and manage user authenticators.
Multi-factor authentication with the Token endpoint
We have expanded MFA support on the Token endpoints to cover the following use cases:
- Use MFA with the password, password-realm, and refresh-token grants.
- Completion of first-time enrollment by users during authentication.
- Selection of the desired MFA authenticator by the user before they execute the MFA challenge.
- Trigger MFA using the API
- Using one-time passwords as the MFA challenge
- Using SMS messages as the MFA challenge
- Tutorial: How to use MFA with the Resource Owner Password Grant
Enrollment and management of user authenticators
The MFA Associate API allows you to create, read, update, and delete authenticators. You can use this API to power user interfaces where users can manage MFA enrollments, or add and remove authenticators.
This enables users to enroll more than one device and select a fallback MFA mechanism in case the primary one is not available. For example, your user might use OTP when their SMS network is not present or unresponsive.
Check out Manage Authenticators for more on listing or deleting authenticators.
Before you start
Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. You can enable the MFA grant by going to Applications > Your Application > Advanced Settings > Grant Types and selecting MFA.
If you are using the MFA API in conjunction with the Token endpoint, you must meet the requirements of the corresponding grant.
The MFA API is designed to work with SMS, Push via Guardian, Email, and OTP factors. It does not currently support enrolling with Duo or with the legacy 'google-authenticator' factor (which can be enrolled using the OTP factor).
Support for authenticator selection is currently limited to the Token Endpoint. Auth0 is working to extend support to Hosted MFA Pages. If users have more than one authenticator enrolled, the most-recently enrolled option will be used by the Hosted MFA Pages.