# 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](https://pocketalert.app/account/security).

## 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.

> **Tip: 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

> **Info: Os scripts continuam funcionando**
>
> O 2FA se aplica a logins interativos. As chaves de API de [Chaves de API](https://pocketalert.app/account/apikeys) 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](https://info.pocketalert.app/api/user/login.md) — o primeiro passo do fluxo de login
- [Introdução](https://info.pocketalert.app/intro.md) — visão geral da autenticação
