Ir para o conteúdo

Autenticação de dois fatores ​

O Pocket Alert oferece autenticação de dois fatores (2FA) com TOTP, tanto no painel web quanto no aplicativo móvel. Depois de ativada, a senha sozinha não dá mais acesso à sua conta.

Configure em Conta → Segurança.

Como configurar ​

  1. Abra Conta → Segurança e inicie a configuração. Você recebe um QR code e uma chave secreta.
  2. Escaneie com qualquer autenticador TOTP — Google Authenticator, 1Password, Authy, Bitwarden.
  3. Digite o código de seis dígitos para confirmar. Só depois de um código correto o 2FA é realmente ativado.
  4. Salve os códigos de recuperação exibidos. Cada um funciona uma única vez.

A configuração interrompida é segura

Iniciar uma nova configuração não altera o seu 2FA atual. A nova chave fica em um espaço pendente e só substitui a ativa depois que você confirmar um código. Assim, fechar a aba no meio do processo não deixa você sem acesso.

Como o login muda ​

Com o 2FA ativado, POST /v1/auth/login não retorna mais um JWT. Ele retorna um desafio de curta duração:

json
{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}

Troque o desafio e um código pelo token definitivo:

POST https://api.pocketalert.app/v1/auth/2fa/login
bash
curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'

Uma troca bem-sucedida retorna o mesmo payload de um login normal: token, name, email, avatar. O campo code aceita um código TOTP de seis dígitos ou um dos seus códigos de recuperação.

Os desafios são válidos por 5 minutos.

As chaves de API não são afetadas ​

Os scripts continuam funcionando

O 2FA se aplica a logins interativos. As chaves de API de Chaves de API autenticam com o header Token e não passam por desafio. Suas tarefas cron, pipelines de CI e hooks de monitoramento continuam enviando alertas exatamente como antes.

Por isso vale a pena limitar cada chave de API a um serviço: revogar uma não afeta as outras.

Códigos de recuperação ​

Os códigos de recuperação são de uso único e consumidos de forma atômica: dois logins em paralelo não conseguem usar o mesmo código. Gere um novo conjunto a qualquer momento em Conta → Segurança. Ao emitir novos códigos, os antigos são invalidados.

Perdeu o autenticador e os códigos? Entre em contato com o suporte. Não existe bypass de autoatendimento, e essa é a ideia.

Proteção contra força bruta ​

Cinco códigos incorretos bloqueiam a conta por 15 minutos, e novas tentativas retornam 429. O contador é zerado em um login bem-sucedido e ao ativar ou desativar o 2FA. Como um desafio permanece válido pelos cinco minutos completos, esse limite de tentativas, e não a duração do desafio, é o que torna impraticável adivinhar um código de seis dígitos.

Notificações por e-mail ​

Você recebe um e-mail sempre que o 2FA é ativado ou desativado na sua conta. Se ele chegar e você não tiver feito a alteração, troque a senha imediatamente.

Endpoints ​

MétodoEndpointFinalidade
GET/v1/auth/2fa/statusSe o 2FA está ativado e quantos códigos de recuperação restam
POST/v1/auth/2fa/setupInicia o cadastro — retorna a chave secreta e o payload do QR code
POST/v1/auth/2fa/enableConfirma um código e ativa o 2FA
POST/v1/auth/2fa/disableDesativa o 2FA — exige um código e sua senha
POST/v1/auth/2fa/recovery-codesEmite um novo conjunto de códigos de recuperação
POST/v1/auth/2fa/loginTroca desafio + código por um JWT (sem header de autenticação)

Todos os endpoints, exceto /auth/2fa/login, exigem uma sessão autenticada.

Relacionados ​

  • Login — o primeiro passo do fluxo de login
  • Introdução — visão geral da autenticação

Documentação do Pocket Alert