> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-factor authentication

> Add a second verification step to user sign-in with an authenticator app or email.

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.

## Supported methods

***

| Method                | How the user gets the passcode                                               | Additional requirement                                 |
| --------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Authenticator app** | A TOTP application generates a six-digit passcode on the user's device.      | The user scans the setup QR code or enters its secret. |
| **Email**             | Access Manager sends a six-digit passcode to the user's saved email address. | The deployment needs an email communication provider.  |

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](/en/platform/access-manager/features/sso/overview).
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.

The MFA token expires after the deployment's configured session time. Auth also limits verification and resend attempts.

<Warning>
  Do not treat an MFA token as an access token. It grants access only to the MFA challenge and verification operations.
</Warning>

## 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. Each recovery code works once. The user can use one when the preferred method is unavailable.

<Warning>
  Store recovery codes when Access Manager issues them. You cannot retrieve the same codes later. Generating a new set invalidates the previous set.
</Warning>

The public Identity API can disable all MFA methods for an account. This operation also removes the account's recovery codes.

## Self-service actions

***

Users can enroll and manage their own MFA methods through the Identity API. The Console guide covers the MFA step during sign-in. Self-service API operations require the authenticated subject to match the user ID in the request path.

## Failure and recovery behavior

***

| Situation                                     | Result                                                                                                                                 |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| The passcode is invalid                       | An invalid passcode evaluated after the preliminary checks counts toward the per-user verification limit.                              |
| The MFA session expires                       | The user must restart sign-in.                                                                                                         |
| The resend limit is reached                   | Auth stops sending new email challenges for that user until the email-method counter expires or successful MFA verification clears it. |
| A recovery code succeeds                      | Access Manager consumes the code so it cannot be used again.                                                                           |
| The user loses every method and recovery code | Contact an administrator and follow your organization's account-recovery procedure.                                                    |

## Next steps

***

<Columns cols={2}>
  <Card title="Complete MFA in the Console" icon="desktop" href="/en/platform/access-manager/features/mfa/console">
    Verify a passcode or use a recovery code during sign-in.
  </Card>

  <Card title="Manage MFA via API" icon="code" href="/en/platform/access-manager/features/mfa/api">
    Use the Auth and Identity operations for enrollment and sign-in.
  </Card>

  <Card title="MFA deployment requirements" icon="server" href="/en/platform/access-manager/features/mfa/deployment">
    Configure MFA session protection, limits, and delivery providers.
  </Card>

  <Card title="Single sign-on" icon="right-to-bracket" href="/en/platform/access-manager/features/sso/overview">
    Use an external identity provider as the first sign-in factor.
  </Card>
</Columns>