🛡️ MFA do Cliente

📋 Visão Geral

A área restrita de MFA cobre o gerenciamento da opção de aplicativo autenticador do cliente logado.

O fluxo é dividido em três etapas: iniciar setup, confirmar setup e remover chave MFA.

🔄 Entidades Envolvidas

• Cliente autenticado
• Opções MFA ativas no escopo atual
• Chave MFA do cliente
• Token de contexto MFA (mfaToken)

📌 Notas e Considerações

• O setup retorna mfaToken e options para continuidade do fluxo.
• A confirmação exige senha atual, código TOTP, chave MFA e mfaToken.
• A remoção elimina a chave MFA atual do cliente.
• A remoção pode ser bloqueada quando a política global de MFA obrigatório está ativa.
• O setup aceita force=true para iniciar novo contexto de configuração mesmo em cenário de MFA obrigatório por política.

🔗 Endpoints Relacionados

📱 Setup de App MFA do Cliente

📋 Descrição

Endpoint responsável por iniciar o setup do app autenticador para o cliente logado, retornando o mfaToken de contexto e a lista de opções MFA elegíveis.

Quando a opção app ainda precisa de configuração, o campo settings inclui os dados de setup: secretKey, otpauth e qrCode.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de Query

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/mfa/app/setup?force=true' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "mfaToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
5    "options": [
6      {
7        "id": 1,
8        "type": "app",
9        "label": "Aplicativo autenticador",
10        "settings": {
11          "secretKey": "JBSWY3DPEHPK3PXP",
12          "otpauth": "otpauth://totp/...",
13          "qrCode": "data:image/png;base64,..."
14        }
15      }
16    ]
17  }
18}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

✅ Confirmação de App MFA do Cliente

📋 Descrição

Endpoint responsável por confirmar o setup do app MFA para o cliente autenticado.

Valida a senha atual do cliente, o código TOTP gerado pelo aplicativo e a chave MFA enviada no setup — e retorna a lista atualizada de opções MFA configuradas.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/mfa/app/confirm' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "mfaToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
7    "secretKey": "JBSWY3DPEHPK3PXP",
8    "code": "123456",
9    "password": "SenhaAtual123"
10  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "options": [
5      {
6        "id": 1,
7        "type": "app",
8        "label": "Aplicativo autenticador",
9        "settings": []
10      }
11    ]
12  }
13}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🗑️ Remoção de Setup de App MFA do Cliente

📋 Descrição

Endpoint responsável por remover a chave MFA atualmente configurada para o cliente autenticado.

A operação pode ser bloqueada quando a política global de MFA obrigatório está ativa na loja.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/mfa/app/setup' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.