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

# Gestiona MFA por API

> Inscribe y gestiona métodos MFA con Identity y luego completa los desafíos MFA con Auth.

MFA usa dos APIs de Access Manager:

* Identity inscribe métodos y gestiona la configuración MFA del usuario.
* Auth completa el segundo paso de verificación durante el inicio de sesión.

Lee [Autenticación multifactor](/es/platform/access-manager/features/mfa/overview) antes de integrar estas operaciones.

## Operaciones de inscripción de cuentas

***

La API de Identity expone estas operaciones de autoservicio:

| Operación                            | Propósito                                         |
| ------------------------------------ | ------------------------------------------------- |
| `POST /v1/users/{id}/mfa/setup`      | Inicia la configuración de `app` o `email`.       |
| `POST /v1/users/{id}/mfa/verify`     | Verifica el código de acceso de configuración.    |
| `POST /v1/users/{id}/mfa/enable`     | Activa el método verificado.                      |
| `GET /v1/users/{id}/mfa`             | Lee el estado MFA actual y los métodos activados. |
| `PATCH /v1/users/{id}/mfa/preferred` | Selecciona el método activado preferido.          |
| `DELETE /v1/users/{id}/mfa`          | Desactiva todos los métodos.                      |

Las operaciones estándar son de autoservicio. El sujeto del bearer token debe coincidir con `{id}`.

### Inicia la configuración

Envía el método en el cuerpo de la solicitud:

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

Esta función admite `app` y `email`.

La configuración de una aplicación de autenticación devuelve un secreto, una URL de código QR y códigos de recuperación. La configuración por correo electrónico devuelve códigos de recuperación y envía un código de acceso a la dirección de correo electrónico guardada del usuario.

### Verifica la configuración

Envía el código de acceso de configuración de 6 a 8 caracteres y el método. La verificación de una aplicación de autenticación también necesita el secreto devuelto por la configuración.

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

### Activa el método

Después de la verificación, activa el método con uno de los códigos de recuperación de la respuesta de configuración. La activación de una aplicación de autenticación también necesita el secreto de configuración.

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

<Warning>
  Trata los secretos de configuración y los códigos de recuperación como credenciales. No los registres en logs ni los almacenes en el control de código fuente.
</Warning>

## Operaciones de inicio de sesión

***

El primer factor usa [Solicitar token de acceso](/es/reference/platform/access-manager/request-access-token). Cuando se requiere MFA, la operación devuelve una respuesta de desafío MFA en lugar de tokens de acceso.

La respuesta incluye:

* `mfaRequired: true`.
* un `mfaToken` de corta duración.
* los métodos activados.
* el método preferido.

### Solicita la entrega por correo electrónico

Usa [Iniciar desafío MFA](/es/reference/platform/access-manager/initiate-mfa-challenge) para el correo electrónico.

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

No solicites la entrega para `app`. La aplicación de autenticación genera el código de acceso localmente.

### Verifica el segundo factor

Usa [Verificar inicio de sesión MFA](/es/reference/platform/access-manager/verify-mfa-login). Envía `passcode` o `recoveryCode`, pero no ambos.

```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"
}
```

Una verificación exitosa devuelve la respuesta estándar de token de acceso. Un código de recuperación se consume después de un uso exitoso.

## Manejo de errores

***

Los errores importantes de inicio de sesión incluyen:

| Código     | Significado                                                         |
| ---------- | ------------------------------------------------------------------- |
| `AUT-0015` | MFA es obligatoria antes de que Auth pueda emitir tokens de acceso. |
| `AUT-0016` | El código de acceso o el código de recuperación no es válido.       |
| `AUT-0017` | La sesión MFA expiró. Reinicia el inicio de sesión.                 |
| `AUT-0018` | Se excedió el límite de verificaciones o reenvíos.                  |
| `AUT-0019` | El método seleccionado todavía necesita configuración.              |
| `AUT-0020` | El token MFA no es válido.                                          |

Identity también puede rechazar un método no admitido, un secreto de configuración faltante, un destino de correo electrónico faltante o una configuración no verificada.

Consulta la [lista de errores de Access Manager](/es/reference/platform/access-manager/access-manager-error-list) para conocer el envelope de error completo y los códigos actuales.

## Páginas relacionadas

***

<Columns cols={2}>
  <Card title="Completa MFA en Console" icon="desktop" href="/es/platform/access-manager/features/mfa/console">
    El flujo del usuario para la verificación durante el inicio de sesión.
  </Card>

  <Card title="APIs de Identity" icon="book" href="/es/reference/platform/access-manager/am-identity-apis">
    La referencia generada para las operaciones de gestión de cuentas.
  </Card>
</Columns>