# Autenticazione a due fattori

Pocket Alert supporta l'autenticazione a due fattori TOTP sia sulla dashboard web sia sull'app mobile. Una volta attivata, la sola password non basta più per accedere al tuo account.

Configurala da [Account → Sicurezza](https://pocketalert.app/account/security).

## Come configurarla

1. Apri **Account → Sicurezza** e avvia la configurazione. Ottieni un codice QR e un segreto.
2. Scansionalo con un qualsiasi authenticator TOTP — Google Authenticator, 1Password, Authy, Bitwarden.
3. Inserisci il codice a sei cifre per confermare. Solo dopo un codice corretto l'autenticazione a due fattori si attiva davvero.
4. Salva i codici di recupero che ti vengono mostrati. Ognuno funziona una sola volta.

> **Tip: La configurazione interrotta è sicura**
>
> Avviare una nuova configurazione non tocca la tua autenticazione a due fattori attuale. Il nuovo segreto finisce in uno slot in attesa e sostituisce quello attivo solo dopo che confermi un codice, quindi chiudere la scheda a metà non ti blocca fuori dall'account.

## Come cambia il login

Con l'autenticazione a due fattori attiva, `POST /v1/auth/login` non restituisce più un JWT. Restituisce una sfida a breve durata:

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

Scambia la sfida insieme a un codice con il token vero:

```
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"
  }'
```

Uno scambio riuscito restituisce lo stesso payload di un login normale — `token`, `name`, `email`, `avatar`. Il campo `code` accetta sia un codice TOTP a sei cifre sia uno dei tuoi codici di recupero.

Le sfide restano valide per **5 minuti**.

## Le chiavi API non sono interessate

> **Info: Gli script continuano a funzionare**
>
> L'autenticazione a due fattori si applica ai login interattivi. Le chiavi API di [Chiavi API](https://pocketalert.app/account/apikeys) si autenticano con l'header `Token` e non ricevono alcuna sfida — i tuoi cron job, le pipeline CI e gli hook di monitoraggio continuano a inviare avvisi esattamente come prima.
>
> Per questo conviene anche assegnare le chiavi API per singolo servizio: revocarne una non interferisce con le altre.

## Codici di recupero

I codici di recupero sono monouso e vengono consumati in modo atomico — due login paralleli non possono usare lo stesso codice. Puoi generarne un nuovo set in qualsiasi momento da **Account → Sicurezza**; emettere nuovi codici invalida quelli vecchi.

Hai perso sia l'authenticator sia i codici? Contatta il supporto. Non esiste un bypass self-service, ed è proprio questo lo scopo.

## Protezione da attacchi brute-force

Cinque codici errati bloccano l'account per **15 minuti**, e i tentativi successivi restituiscono `429`. Il contatore si azzera a un login riuscito e quando attivi o disattivi l'autenticazione a due fattori. Poiché una sfida resta valida per i suoi cinque minuti interi, è questo limite di tentativi — non la durata della sfida — a rendere impraticabile l'indovinare un codice a sei cifre.

## Notifiche email

Ricevi un'email ogni volta che l'autenticazione a due fattori viene attivata o disattivata sul tuo account. Se ne arriva una e non sei stato tu, è il segnale per cambiare subito la password.

## Endpoint

| Metodo | Endpoint | Scopo |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | Indica se l'autenticazione a due fattori è attiva e quanti codici di recupero restano |
| `POST` | `/v1/auth/2fa/setup` | Avvia la registrazione — restituisce il segreto e il payload del QR |
| `POST` | `/v1/auth/2fa/enable` | Conferma un codice e attiva l'autenticazione a due fattori |
| `POST` | `/v1/auth/2fa/disable` | Disattiva l'autenticazione a due fattori — richiede un codice e la tua password |
| `POST` | `/v1/auth/2fa/recovery-codes` | Emette un nuovo set di codici di recupero |
| `POST` | `/v1/auth/2fa/login` | Scambia sfida + codice con un JWT (nessun header di autenticazione) |

Ogni endpoint tranne `/auth/2fa/login` richiede una sessione autenticata.

## Correlati

- [Login](https://info.pocketalert.app/api/user/login.md) — il primo passo del flusso di login
- [Introduzione](https://info.pocketalert.app/intro.md) — panoramica sull'autenticazione
