Skip to main content
Multi-factor authentication (MFA) requires a user to prove their identity twice. The user first signs in with a password or single sign-on. Access Manager then asks for a passcode or recovery code before it issues access tokens. MFA applies to user accounts. It does not apply to machine-to-machine applications that use client credentials. A passkey sign-in does not ask for a second factor.

​
Supported methods

A user can enable more than one method and select one as the preferred method. The preferred method appears first during sign-in, but the user can select another enabled method.

​
How MFA sign-in works

  1. The user signs in with a password or single sign-on.
  2. Auth validates the first factor.
  3. If MFA is enabled for the user, Auth returns a short-lived MFA token instead of access tokens.
  4. The user selects one of the enabled methods.
  5. For email, Auth sends a challenge code. An authenticator app generates its code locally.
  6. The user submits a six-digit passcode or one recovery code.
  7. Auth verifies the second factor and returns the access tokens.
If the organization requires an MFA method that the user has not enrolled, Auth answers error AUT-0019 with an MFA token that is valid only for enrollment. This happens at step 3 when the user has no MFA method, or at step 7 when the user has a method but not every required method. The user sets up and confirms one of the listed methods with that token, and then continues from step 4 with the same token. Read Enroll a required method. The MFA token expires after the deployment’s configured session time. Enrollment during sign-in does not extend it. Auth also limits verification and resend attempts.
Do not treat an MFA token as an access token. It grants access only to the MFA enrollment, challenge, and verification operations of sign-in.

​
Setup and recovery codes

A user must set up and verify a method before enabling it. The setup differs by method:
  • An authenticator app setup returns a QR-code URL and a secret.
  • Email setup sends a verification code to the saved email address.
Access Manager issues recovery codes during MFA enrollment. Enrollment during sign-in issues one recovery code. Each recovery code works once. The user can use one when the preferred method is unavailable.
Store recovery codes when Access Manager issues them. You cannot retrieve the same codes later. Generating a new set invalidates the previous set.
The public Identity API can disable all MFA methods for an account. This operation also removes the account’s recovery codes. To turn off MFA, send the code that the Disable MFA reference describes.

​
Self-service actions

Users can enroll and manage their own MFA methods in the Console, under Settings › Security, or through the Identity API. A user can also enroll a method that the organization requires during sign-in, through the Auth API. In the Console, a user can enable an authenticator app or email, remove a method, choose the default method, and generate recovery codes. The Console guide covers MFA at sign-in and removing a method. Self-service API operations require the authenticated subject to match the user ID in the request path.

​
Failure and recovery behavior

​
Next steps

Complete MFA in the Console

Verify a passcode or use a recovery code during sign-in.

Manage MFA via API

Use the Auth and Identity operations for enrollment and sign-in.

MFA deployment requirements

Configure MFA session protection, limits, and delivery providers.

Single sign-on

Use an external identity provider as the first sign-in factor.