Multi-factor Authentication API

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 MFA factors.

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.

More information

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