Integrar autenticação multi-fator (MFA) na sua aplicação não precisa ser complicado. Com a API do Authentik, você pode adicionar MFA via RCS e WhatsApp em poucos minutos, sem SDKs pesados ou configurações complexas.

Neste tutorial, vamos percorrer cada etapa do processo: desde a criação da sua conta até a verificação do código OTP. Ao final, você terá uma integração funcionando em produção.

Pré-requisitos

Antes de começar, você vai precisar de:

Passo 1: Criar seu App no painel

PASSO 1

Após criar sua conta, acesse o painel do Authentik e crie um novo App. Cada App representa uma aplicação ou serviço que vai utilizar MFA.

No painel, navegue até Configurações > Apps e clique em "Novo App". Você vai precisar informar:

Após criar o App, você receberá um app_id e uma api_key. Guarde essas credenciais em local seguro.

Nunca exponha sua api_key no frontend. Todas as chamadas a API do Authentik devem ser feitas pelo seu backend.

Passo 2: Enviar solicitação de autenticação

PASSO 2

Com suas credenciais em mãos, você pode enviar a primeira solicitação de autenticação. A API do Authentik aceita requisições REST simples:

# Enviar autenticação via RCS
curl -X POST https://api.authentik.com.br/v1/auth/send \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511999998888",
    "channel": "rcs",
    "app_id": "app_xpto123",
    "callback_url": "https://seusite.com/webhook/auth",
    "metadata": {
      "user_id": "usr_456",
      "action": "login"
    }
  }'

A resposta da API será:

{
  "auth_id": "auth_abc123def456",
  "status": "sent",
  "channel": "rcs",
  "expires_at": "2026-03-24T15:05:00Z",
  "otp_length": 6
}

O parâmetro channel aceita três valores: rcs, whatsapp ou auto (o Authentik escolhe o melhor canal disponível para o usuário).

O campo metadata é opcional e permite que você associe dados do seu sistema a autenticação. Esses dados seráo devolvidos no webhook callback.

Passo 3: Receber o webhook callback

PASSO 3

Quando o usuário interáge com a mensagem de autenticação (toca no botao "Confirmar" no RCS ou envia o código no WhatsApp), o Authentik envia um webhook para a URL configurada:

// POST https://seusite.com/webhook/auth
// Headers: X-Authentik-Signature: sha256=...
{
  "event": "auth.confirmed",
  "auth_id": "auth_abc123def456",
  "phone": "+5511999998888",
  "channel": "rcs",
  "status": "confirmed",
  "confirmed_at": "2026-03-24T14:30:12Z",
  "otp": "847293",
  "metadata": {
    "user_id": "usr_456",
    "action": "login"
  }
}

Eventos possíveis no webhook:

Sempre valide o header X-Authentik-Signature para garantir que o webhook veio do Authentik. A assinatura é gerada com HMAC-SHA256 usando seu webhook secret.

Passo 4: Verificar o OTP

PASSO 4

Se você estiver usando o modo OTP (onde o usuário digita o código na sua aplicação em vez de tocar um botao), pode verificar o código diretamente pela API:

# Verificar código OTP
curl -X POST https://api.authentik.com.br/v1/auth/verify \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_id": "auth_abc123def456",
    "otp": "847293"
  }'

Resposta em caso de sucesso:

{
  "valid": true,
  "auth_id": "auth_abc123def456",
  "verified_at": "2026-03-24T14:30:45Z"
}

Resposta em caso de falha:

{
  "valid": false,
  "error": "invalid_otp",
  "attempts_remaining": 2
}

O Authentik permite no máximo 3 tentativas de verificação por autenticação. Após 3 tentativas inválidas, o auth_id é invalidado e você precisa enviar uma nova solicitação.

Testando sua integração

O Authentik oferece um modo sandbox para testes sem custo. Para ativar o modo de teste, adicione o header X-Authentik-Sandbox: true na sua requisicao:

curl -X POST https://api.authentik.com.br/v1/auth/send \
  -H "Authorization: Bearer sua_api_key" \
  -H "X-Authentik-Sandbox: true" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511999998888",
    "channel": "rcs",
    "app_id": "app_xpto123"
  }'

No modo sandbox, a mensagem não é enviada de fato, mas o fluxo completo é simulado. O OTP de teste sempre será 123456.

Próximos passos

Com a integração básica funcionando, você pode explorar recursos avançados:

Para mais detalhes, consulte a documentação completa da API.