# Authentification à deux facteurs

Pocket Alert prend en charge l’authentification à deux facteurs TOTP, aussi bien sur le tableau de bord web que sur l’application mobile. Une fois activée, un mot de passe seul ne suffit plus à accéder à votre compte.

Configurez-la dans [Compte → Sécurité](https://pocketalert.app/account/security).

## Mise en place

1. Ouvrez **Compte → Sécurité** et lancez la configuration. Vous obtenez un code QR et une clé secrète.
2. Scannez-le avec n’importe quelle application d’authentification TOTP : Google Authenticator, 1Password, Authy, Bitwarden.
3. Saisissez le code à six chiffres pour confirmer. Ce n’est qu’après un code correct que la 2FA est réellement activée.
4. Enregistrez les codes de récupération qui vous sont affichés. Chacun ne fonctionne qu’une seule fois.

> **Tip: Configuration interrompue sans risque**
>
> Lancer une nouvelle configuration ne modifie pas votre 2FA existante. La nouvelle clé est placée dans un emplacement en attente et ne remplace la clé active qu’après la confirmation d’un code. Fermer l’onglet à mi-parcours ne peut donc pas vous bloquer l’accès.

## Ce qui change à la connexion

Avec la 2FA activée, `POST /v1/auth/login` ne renvoie plus de JWT. Il renvoie un défi à courte durée de vie :

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

Échangez le défi et un code contre le jeton réel :

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

Un échange réussi renvoie la même charge utile qu’une connexion classique : `token`, `name`, `email`, `avatar`. Le champ `code` accepte soit un code TOTP à six chiffres, soit l’un de vos codes de récupération.

Les défis sont valables **5 minutes**.

## Les clés API ne sont pas concernées

> **Info: Les scripts continuent de fonctionner**
>
> La 2FA s’applique aux connexions interactives. Les clés API issues de [Clés API](https://pocketalert.app/account/apikeys) s’authentifient avec l’en-tête `Token` et ne sont pas soumises à un défi. Vos tâches cron, pipelines CI et webhooks de supervision continuent d’envoyer leurs alertes exactement comme avant.
>
> C’est aussi pour cela qu’il est judicieux de limiter chaque clé API à un service : révoquer l’une n’affecte pas les autres.

## Codes de récupération

Les codes de récupération sont à usage unique et consommés de manière atomique : deux connexions simultanées ne peuvent pas utiliser le même code. Vous pouvez générer un nouvel ensemble à tout moment depuis **Compte → Sécurité** ; la création de nouveaux codes invalide les anciens.

Vous avez perdu à la fois votre application d’authentification et vos codes ? Contactez le support. Il n’existe pas de contournement en libre-service, et c’est voulu.

## Protection contre les attaques par force brute

Cinq codes erronés verrouillent le compte pendant **15 minutes**, et toute nouvelle tentative renvoie `429`. Le compteur est réinitialisé lors d’une connexion réussie, ainsi qu’à l’activation ou à la désactivation de la 2FA. Comme un défi reste valable pendant ses cinq minutes complètes, c’est cette limite de tentatives, et non la durée de vie du défi, qui rend impraticable la devinette d’un code à six chiffres.

## Notifications par e-mail

Vous recevez un e-mail chaque fois que la 2FA est activée ou désactivée sur votre compte. Si vous en recevez un alors que vous n’êtes pas à l’origine de cette action, changez immédiatement votre mot de passe.

## Points de terminaison

| Méthode | Point de terminaison | Rôle |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | Indique si la 2FA est activée et combien de codes de récupération restent |
| `POST` | `/v1/auth/2fa/setup` | Démarrer l’inscription : renvoie la clé secrète et la charge utile du code QR |
| `POST` | `/v1/auth/2fa/enable` | Confirmer un code et activer la 2FA |
| `POST` | `/v1/auth/2fa/disable` | Désactiver la 2FA : nécessite un code et votre mot de passe |
| `POST` | `/v1/auth/2fa/recovery-codes` | Générer un nouvel ensemble de codes de récupération |
| `POST` | `/v1/auth/2fa/login` | Échanger défi + code contre un JWT (sans en-tête d’authentification) |

Tous les points de terminaison, sauf `/auth/2fa/login`, exigent une session authentifiée.

## Voir aussi

- [Connexion](https://info.pocketalert.app/api/user/login.md) — la première étape du flux de connexion
- [Introduction](https://info.pocketalert.app/intro.md) — vue d’ensemble de l’authentification
