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

# Gerenciar a MFA pela API

> Cadastre e gerencie métodos de MFA com o Identity e conclua os desafios de MFA com o Auth.

A MFA usa duas APIs do Access Manager:

* O Identity cadastra os métodos e gerencia as configurações de MFA do usuário.
* O Auth conclui a segunda etapa de verificação durante a entrada.

Leia [Autenticação multifator](/pt/platform/access-manager/features/mfa/overview) antes de integrar essas operações.

## Operações de adesão da conta

***

A API do Identity expõe estas operações de autoatendimento:

| Operação                             | Finalidade                                         |
| ------------------------------------ | -------------------------------------------------- |
| `POST /v1/users/{id}/mfa/setup`      | Inicia a configuração de `app` ou `email`.         |
| `POST /v1/users/{id}/mfa/verify`     | Verifica o código de acesso da configuração.       |
| `POST /v1/users/{id}/mfa/enable`     | Habilita o método verificado.                      |
| `GET /v1/users/{id}/mfa`             | Lê o status atual da MFA e os métodos habilitados. |
| `PATCH /v1/users/{id}/mfa/preferred` | Seleciona o método habilitado preferencial.        |
| `DELETE /v1/users/{id}/mfa`          | Desabilita todos os métodos.                       |

As operações padrão são de autoatendimento. O subject do bearer token precisa corresponder a `{id}`.

### Iniciar a configuração

Envie o método no corpo da requisição:

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

Este recurso aceita `app` e `email`.

A configuração do aplicativo autenticador retorna um segredo, uma URL de código QR e códigos de recuperação. A configuração por email retorna códigos de recuperação e envia um código de acesso ao endereço de email salvo do usuário.

### Verificar a configuração

Envie o código de acesso da configuração, com 6 a 8 caracteres, e o método. A verificação do aplicativo autenticador também precisa do segredo retornado pela configuração.

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

### Habilitar o método

Depois da verificação, habilite o método com um código de recuperação da resposta de configuração. A habilitação do aplicativo autenticador também precisa do segredo da configuração.

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

<Warning>
  Trate os segredos de configuração e os códigos de recuperação como credenciais. Não os registre em logs nem os armazene no controle de versão.
</Warning>

## Operações de entrada

***

O primeiro fator usa [Solicitar token de acesso](/pt/reference/platform/access-manager/request-access-token). Quando a MFA é obrigatória, a operação retorna uma resposta de desafio de MFA em vez de tokens de acesso.

A resposta inclui:

* `mfaRequired: true`.
* um `mfaToken` de curta duração.
* os métodos habilitados.
* o método preferencial.

### Solicitar a entrega por email

Use [Iniciar desafio de MFA](/pt/reference/platform/access-manager/initiate-mfa-challenge) para email.

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

Não solicite a entrega para `app`. O aplicativo autenticador gera o código de acesso localmente.

### Verificar o segundo fator

Use [Verificar entrada com MFA](/pt/reference/platform/access-manager/verify-mfa-login). Envie `passcode` ou `recoveryCode`, nunca os dois.

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

Uma verificação bem-sucedida retorna a resposta padrão de token de acesso. Um código de recuperação é consumido depois de um uso bem-sucedido.

## Tratamento de erros

***

Os erros de entrada importantes incluem:

| Código     | Significado                                                         |
| ---------- | ------------------------------------------------------------------- |
| `AUT-0015` | A MFA é obrigatória antes que o Auth possa emitir tokens de acesso. |
| `AUT-0016` | O código de acesso ou de recuperação é inválido.                    |
| `AUT-0017` | A sessão de MFA expirou. Reinicie a entrada.                        |
| `AUT-0018` | O limite de verificações ou reenvios foi excedido.                  |
| `AUT-0019` | O método selecionado ainda precisa ser configurado.                 |
| `AUT-0020` | O token de MFA é inválido.                                          |

O Identity também pode recusar um método não compatível, um segredo de configuração ausente, um destino de email ausente ou uma configuração não verificada.

Veja a [lista de erros do Access Manager](/pt/reference/platform/access-manager/access-manager-error-list) para consultar o envelope completo dos erros e os códigos atuais.

## Páginas relacionadas

***

<Columns cols={2}>
  <Card title="Conclua a MFA no Console" icon="desktop" href="/pt/platform/access-manager/features/mfa/console">
    O fluxo do usuário para verificação durante a entrada.
  </Card>

  <Card title="APIs do Identity" icon="book" href="/pt/reference/platform/access-manager/am-identity-apis">
    A referência gerada para as operações de gerenciamento de contas.
  </Card>
</Columns>