> ## 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](https://docs.lerian.studio/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. |
| `DELETE /v1/users/{id}/mfa/{mfaType}` | Desabilita um método. |
| `POST /v1/users/{id}/mfa/recovery-codes` | Gera um novo conjunto de códigos de recuperação. O conjunto anterior deixa de funcionar. |

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.

### Desabilitar a MFA ou remover um método

Para desabilitar a MFA, envie o código que a referência [Desabilitar MFA](https://docs.lerian.studio/pt/reference/platform/access-manager/disable-mfa.md) descreve. Para remover o aplicativo autenticador ou o método de email, envie um código desse método.

Para receber o código por email, chame `POST /v1/users/{id}/mfa/disable/challenge`. Somente o próprio usuário pode solicitá-lo, e somente quando o método de email está habilitado. O código é válido por 10 minutos e aceita 5 tentativas erradas. Um usuário pode solicitar 3 códigos em 15 minutos.

### Operações de administrador

Um administrador gerencia os métodos de outro usuário com mais duas operações. `{id}` é o usuário de destino. O bearer token precisa da permissão `mfa-admin` com a ação `post` para habilitar um método e da ação `delete` para remover um.

| Operação | Finalidade |
| - | - |
| [`POST /v1/users/{id}/mfa/admin/enable`](https://docs.lerian.studio/pt/reference/platform/access-manager/admin-enable-mfa) | Habilita `email` para o usuário de destino sem configuração nem verificação. A resposta contém os códigos de recuperação do usuário de destino. |
| [`DELETE /v1/users/{id}/mfa/admin/{mfaType}`](https://docs.lerian.studio/pt/reference/platform/access-manager/admin-disable-mfa) | Remove um método (`app`, `email` ou uma adesão legada de `sms`) do usuário de destino. A operação não pede código. |

## Operações de entrada

***

O primeiro fator usa [Solicitar token de acesso](https://docs.lerian.studio/pt/reference/platform/access-manager/request-access-token.md). Quando o usuário tem a MFA habilitada, 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.

### Cadastrar um método exigido

Quando o usuário não tem nenhum método de MFA e a organização exige um, [Solicitar token de acesso](https://docs.lerian.studio/pt/reference/platform/access-manager/request-access-token.md) responde `401` com o erro `AUT-0019` em vez de um desafio de MFA. [Verificar login por MFA](https://docs.lerian.studio/pt/reference/platform/access-manager/verify-mfa-login.md) dá a mesma resposta quando o usuário tem um método, mas não todos os métodos exigidos. O corpo do erro também tem:

* `mfaToken`: um token válido apenas para a adesão.
* `availableMethods`: os métodos que o usuário pode cadastrar, `app` ou `email`.

1. Inicie a configuração com [Iniciar adesão à MFA](https://docs.lerian.studio/pt/reference/platform/access-manager/start-enrolling-a-required-mfa-factor.md).

   ```json Request theme={null}
   {
     "mfaToken": "enrollment-mfa-token",
     "mfaType": "app"
   }
   ```

   Para `app`, a resposta tem um `secret` e uma `url` para o aplicativo autenticador. Para `email`, o Access Manager envia um código ao endereço de email salvo do usuário. A resposta sempre tem um código de recuperação em `recoveryCodes`. Guarde-o: você não poderá recuperá-lo depois. Uma nova chamada de configuração substitui a configuração anterior.
2. Confirme o método com [Confirmar adesão à MFA](https://docs.lerian.studio/pt/reference/platform/access-manager/confirm-an-mfa-enrollment-and-continue-the-login.md). Envie o código de acesso do aplicativo autenticador ou do email.

   ```json Request theme={null}
   {
     "mfaToken": "enrollment-mfa-token",
     "mfaType": "app",
     "passcode": "123456"
   }
   ```

   O Access Manager habilita o método e retorna uma resposta de desafio de MFA com o mesmo `mfaToken`. Continue com [Solicitar a entrega por email](#request-email-delivery) para email e, depois, com [Verificar o segundo fator](#verify-the-second-factor).

Códigos de acesso errados contam para o mesmo limite por usuário da verificação (`AUT-0018`). O token de MFA mantém a duração que tinha no primeiro fator, então conclua a adesão e a verificação dentro de uma sessão de MFA.

### Solicitar a entrega por email

Use [Iniciar desafio de MFA](https://docs.lerian.studio/pt/reference/platform/access-manager/initiate-mfa-challenge.md) 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 login por MFA](https://docs.lerian.studio/pt/reference/platform/access-manager/verify-mfa-login.md). 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, a menos que o usuário ainda tenha um método exigido a cadastrar (`AUT-0019`). 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-0016` | O código de acesso é inválido ou, em Iniciar adesão à MFA, o método não é um que o usuário deve cadastrar. |
| `AUT-0017` | A sessão de MFA expirou, ou o token de MFA não é válido para esta etapa. Reinicie a entrada. |
| `AUT-0018` | O limite de verificações foi excedido. |
| `AUT-0019` | A organização exige um método de MFA que o usuário não cadastrou. Cadastre-o com o token de MFA retornado. |
| `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](https://docs.lerian.studio/pt/reference/platform/access-manager/access-manager-error-list.md) para consultar o envelope completo dos erros e os códigos atuais.

## Páginas relacionadas

***

> [card] [Conclua a MFA no Console](https://docs.lerian.studio/pt/platform/access-manager/features/mfa/console.md)
>
> O fluxo do usuário para verificação durante a entrada.

> [card] [APIs do Identity](https://docs.lerian.studio/pt/reference/platform/access-manager/am-identity-apis.md)
>
> A referência gerada para as operações de gerenciamento de contas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.