Auth21 Kernel
Inicio Entrar

Auth21 Kernel | Verification Layer

Use o mesmo challenge para qualquer acao sensivel

Nao construa OTP, approve-link e cross-device para cada caso de uso. Reaproveite a camada de verificacao da Auth21 em login, password reset, alteracao de email, admin action e fluxos customizados.

Challenge

Crie uma verificacao

Dispare um challenge por email e receba OTP URL, approval URL e trace.

Ver endpoints

Aprovacao

OTP ou approve-link

O mesmo challenge pode ser concluido por codigo manual ou por aprovacao de link.

Ver respostas

Hosted

UX pronta

As hosted pages do Mail2FA continuam sendo usadas aqui como camada de verificacao.

Ver hosted pages

Auth21 Verification Layer

A Verification Layer transforma o motor atual de challenge da Auth21 em uma camada reutilizavel para qualquer acao sensivel da sua aplicacao. O objetivo nao e criar outro produto separado do login. O objetivo e permitir que a mesma infraestrutura de email, OTP, approve-link e cross-device seja usada em login, troca de senha, alteracao de email, acao administrativa e casos customizados.

Mensagem principal: Auth21 continua sendo uma plataforma de identidade. A Verification Layer e a camada nativa de verificacao que reaproveita o mesmo challenge em qualquer operacao sensivel.

Como funciona

Sua aplicacao
      ↓
POST /verification/challenge
      ↓
Auth21 gera challenge e envia email
      ↓
Usuario escolhe:
- digitar OTP
- aprovar por link
      ↓
POST /verification/verify ou POST /verification/approve
      ↓
Sua aplicacao conclui a acao sensivel

Quando o fluxo for cross-device, a pagina hosted do desktop continua aguardando o status do challenge enquanto o usuario pode aprovar pelo email em outro device.

Endpoints

  • POST /verification/challenge: cria o challenge e dispara o email.
  • POST /verification/verify: verifica o OTP digitado pelo usuario.
  • POST /verification/approve: aprova a acao por link/token sem OTP.
  • GET /verification/status: consulta o status atual do challenge server-to-server.
  • GET /verification/verify-page: pagina hosted para OTP manual.
  • GET /verification/authorize-page: pagina hosted para autorizacao por link.

Payload de challenge

{
  "client_id": "app_client_id",
  "client_secret": "app_client_secret",
  "subject": "user-123",
  "email": "user@example.com",
  "user_name": "Laura Mendes",
  "action": "admin_action",
  "return_to": "https://cliente.app/api/verification-complete"
}

Envie sempre user_name, name ou full_name quando quiser que o Email Studio preencha o nome real do usuario no template.

Respostas principais

Challenge

{
  "status": "pass",
  "capability": "verification",
  "channel": "email",
  "challenge_type": "admin_action",
  "challenge_token": "token",
  "otp_url": "https://auth21.cloud/verification/verify-page?...",
  "approval_url": "https://auth21.cloud/verification/authorize-page?...",
  "verification_mode": "otp_or_link",
  "expires_at": "2026-06-01 15:30:00",
  "trace_id": "..."
}

Verify / Approve

{
  "status": "pass",
  "decision": "allow",
  "capability": "verification",
  "challenge_type": "admin_action",
  "verification_mode": "otp|approval_link",
  "reason_code": "TWO_FACTOR_VERIFIED",
  "trace_id": "..."
}

Casos de uso

Login

Use action=login ou login_step_up quando quiser pedir OTP/link durante autenticacao.

Troca de senha

Use password_change para obrigar challenge antes de alterar credenciais.

Alteracao de email

Use change_email ou security_settings para validar identidade.

Acao customizada

Use custom_action ou um nome proprio como approve_payment, desde que o escopo esteja habilitado na policy.

Politica e escopos

A Verification Layer respeita a mesma policy da tela de 2FA. Isso significa que a app pode habilitar ou nao o uso por area:

  • Login
  • Troca de senha
  • Configuracoes de seguranca
  • Acoes administrativas sensiveis
  • Acoes customizadas

Hosted pages

A mesma infraestrutura hosted do Mail2FA e reaproveitada aqui:

  • /verification/verify-page: fluxo OTP manual hosted.
  • /verification/authorize-page: aprovacao por link com um clique.

No email, o botao e o placeholder de link apontam para a pagina de autorizacao por link. O otp_url continua disponivel quando a app quiser expor a pagina manual com campo de codigo.

Checklist de integracao

  1. Crie a app no Console.
  2. Ative e configure a policy da tela 2FA.
  3. Escolha Padrao Auth21 ou publique uma versao do Email Studio no Hub.
  4. No backend, chame POST /verification/challenge.
  5. Conclua por /verification/verify ou /verification/approve.
  6. Consulte /verification/status quando houver cross-device.
  7. So conclua a sessao local ou a acao sensivel depois de decision=allow.