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
- Abra Conta → Segurança e inicie a configuração. Você recebe um QR code e uma chave secreta.
- Escaneie com qualquer autenticador TOTP — Google Authenticator, 1Password, Authy, Bitwarden.
- Digite o código de seis dígitos para confirmar. Só depois de um código correto o 2FA é realmente ativado.
- 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:
{
"two_factor_required": true,
"challenge": "eyJhbGciOiJIUzI1NiIs…"
}Troque o desafio e um código pelo token definitivo:
POST https://api.pocketalert.app/v1/auth/2fa/logincurl -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étodo | Endpoint | Finalidade |
|---|---|---|
GET | /v1/auth/2fa/status | Se o 2FA está ativado e quantos códigos de recuperação restam |
POST | /v1/auth/2fa/setup | Inicia o cadastro — retorna a chave secreta e o payload do QR code |
POST | /v1/auth/2fa/enable | Confirma um código e ativa o 2FA |
POST | /v1/auth/2fa/disable | Desativa o 2FA — exige um código e sua senha |
POST | /v1/auth/2fa/recovery-codes | Emite um novo conjunto de códigos de recuperação |
POST | /v1/auth/2fa/login | Troca 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