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

# Manage MFA via API

> Enroll and manage MFA methods with Identity, then complete MFA challenges with Auth.

MFA uses two Access Manager APIs:

* Identity enrolls methods and manages the user's MFA settings.
* Auth completes the second verification step during sign-in.

Read [Multi-factor authentication](/en/platform/access-manager/features/mfa/overview) before you integrate these operations.

## Account enrollment operations

***

The Identity API exposes these self-service operations:

| Operation                            | Purpose                                          |
| ------------------------------------ | ------------------------------------------------ |
| `POST /v1/users/{id}/mfa/setup`      | Start setup for `app` or `email`.                |
| `POST /v1/users/{id}/mfa/verify`     | Verify the setup passcode.                       |
| `POST /v1/users/{id}/mfa/enable`     | Enable the verified method.                      |
| `GET /v1/users/{id}/mfa`             | Read the current MFA status and enabled methods. |
| `PATCH /v1/users/{id}/mfa/preferred` | Select the preferred enabled method.             |
| `DELETE /v1/users/{id}/mfa`          | Disable all methods.                             |

The standard operations are self-service. The bearer-token subject must match `{id}`.

### Start setup

Send the method in the request body:

```json Request theme={null}
{
  "mfaType": "app"
}
```

This feature supports `app` and `email`.

Authenticator-app setup returns a secret, a QR-code URL, and recovery codes. Email setup returns recovery codes and sends a passcode to the user's saved email address.

### Verify setup

Submit the 6–8-character setup passcode and the method. Authenticator-app verification also needs the secret returned by setup.

```json Request theme={null}
{
  "mfaType": "app",
  "passcode": "123456",
  "secret": "setup-secret"
}
```

### Enable the method

After verification, enable the method with one recovery code from the setup response. Authenticator-app enablement also needs the setup secret.

```json Request theme={null}
{
  "mfaType": "app",
  "secret": "setup-secret",
  "recoveryCode": "recovery-code"
}
```

<Warning>
  Treat setup secrets and recovery codes as credentials. Do not log them or store them in source control.
</Warning>

## Login operations

***

The first factor uses [Request Access Token](/en/reference/platform/access-manager/request-access-token). When MFA is required, the operation returns an MFA challenge response instead of access tokens.

The response includes:

* `mfaRequired: true`.
* a short-lived `mfaToken`.
* the enabled methods.
* the preferred method.

### Request email delivery

Use [Initiate MFA Challenge](/en/reference/platform/access-manager/initiate-mfa-challenge) for email.

```json Request theme={null}
{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "email"
}
```

Do not request delivery for `app`. The authenticator app generates the passcode locally.

### Verify the second factor

Use [Verify MFA Login](/en/reference/platform/access-manager/verify-mfa-login). Send either `passcode` or `recoveryCode`, not both.

```json Passcode theme={null}
{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "passcode": "123456"
}
```

```json Recovery code theme={null}
{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "recoveryCode": "unused-recovery-code"
}
```

A successful verification returns the standard access-token response. A recovery code is consumed after one successful use.

## Error handling

***

Important login errors include:

| Code       | Meaning                                              |
| ---------- | ---------------------------------------------------- |
| `AUT-0015` | MFA is required before Auth can issue access tokens. |
| `AUT-0016` | The passcode or recovery code is invalid.            |
| `AUT-0017` | The MFA session expired. Restart sign-in.            |
| `AUT-0018` | The verification or resend limit was exceeded.       |
| `AUT-0019` | The selected method still needs setup.               |
| `AUT-0020` | The MFA token is invalid.                            |

Identity can also reject an unsupported method, missing setup secret, missing email destination, or unverified setup.

See the [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list) for the full error envelope and current codes.

## Related pages

***

<Columns cols={2}>
  <Card title="Complete MFA in the Console" icon="desktop" href="/en/platform/access-manager/features/mfa/console">
    The user workflow for verification during sign-in.
  </Card>

  <Card title="Identity APIs" icon="book" href="/en/reference/platform/access-manager/am-identity-apis">
    The generated reference for account-management operations.
  </Card>
</Columns>