# Zwei-Faktor-Authentifizierung

Pocket Alert unterstützt TOTP-Zwei-Faktor-Authentifizierung im Web-Dashboard und in der mobilen App. Sobald sie aktiviert ist, reicht ein Passwort allein nicht mehr, um dich in dein Konto zu bringen.

Richte sie unter [Konto → Sicherheit](https://pocketalert.app/account/security) ein.

## Einrichtung

1. Öffne **Konto → Sicherheit** und starte die Einrichtung. Du bekommst einen QR-Code und einen Schlüssel angezeigt.
2. Scanne ihn mit einer beliebigen TOTP-App — Google Authenticator, 1Password, Authy, Bitwarden.
3. Gib den sechsstelligen Code zur Bestätigung ein. Erst nach einem korrekten Code wird 2FA tatsächlich aktiviert.
4. Speichere die Wiederherstellungscodes, die dir angezeigt werden. Jeder davon funktioniert nur einmal.

> **Tip: Unterbrochene Einrichtung ist unbedenklich**
>
> Eine neue Einrichtung verändert deine bestehende 2FA nicht. Der neue Schlüssel landet in einem wartenden Slot und ersetzt den aktiven erst, nachdem du einen Code bestätigt hast. Wenn du den Tab mittendrin schließt, kannst du dich also nicht aussperren.

## Wie sich der Login ändert

Mit aktivierter 2FA liefert `POST /v1/auth/login` kein JWT mehr zurück. Stattdessen kommt eine kurzlebige Challenge:

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

Tausche die Challenge zusammen mit einem Code gegen das echte Token ein:

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

Ein erfolgreicher Tausch liefert dieselben Daten wie ein normaler Login — `token`, `name`, `email`, `avatar`. Das Feld `code` akzeptiert entweder einen sechsstelligen TOTP-Code oder einen deiner Wiederherstellungscodes.

Challenges sind **5 Minuten** gültig.

## API-Schlüssel bleiben unberührt

> **Info: Skripte laufen weiter**
>
> 2FA gilt für interaktive Logins. API-Schlüssel aus [API-Schlüssel](https://pocketalert.app/account/apikeys) authentifizieren sich mit dem Header `Token` und werden nicht abgefragt. Deine Cronjobs, CI-Pipelines und Monitoring-Hooks senden Benachrichtigungen also genau wie bisher.
>
> Deshalb lohnt es sich, API-Schlüssel pro Dienst zu beschränken: Wenn du einen widerrufst, beeinflusst das die anderen nicht.

## Wiederherstellungscodes

Wiederherstellungscodes sind Einmalcodes und werden atomar verbraucht — zwei parallele Logins können also nicht denselben Code verbrauchen. Du kannst jederzeit einen neuen Satz unter **Konto → Sicherheit** erzeugen. Neue Codes machen die alten ungültig.

Hast du sowohl deine TOTP-App als auch deine Codes verloren? Kontaktiere den Support. Eine Umgehung im Selbstservice gibt es nicht, und genau das ist der Sinn der Sache.

## Schutz vor Brute-Force-Angriffen

Fünf fehlgeschlagene Codes sperren das Konto für **15 Minuten**, weitere Versuche liefern `429`. Der Zähler wird bei einem erfolgreichen Login sowie beim Aktivieren oder Deaktivieren von 2FA zurückgesetzt. Da eine Challenge ihre vollen fünf Minuten gültig bleibt, ist diese Versuchsbegrenzung — und nicht die Lebensdauer der Challenge — das, was das Erraten eines sechsstelligen Codes unpraktikabel macht.

## E-Mail-Benachrichtigungen

Du bekommst eine E-Mail, wann immer 2FA für dein Konto aktiviert oder deaktiviert wird. Wenn du eine solche E-Mail erhältst und du das nicht warst, ist das dein Signal, das Passwort sofort zu ändern.

## Endpunkte

| Methode | Endpunkt | Zweck |
|--------|----------|---------|
| `GET` | `/v1/auth/2fa/status` | Ob 2FA aktiviert ist und wie viele Wiederherstellungscodes noch übrig sind |
| `POST` | `/v1/auth/2fa/setup` | Registrierung starten — gibt Schlüssel und QR-Daten zurück |
| `POST` | `/v1/auth/2fa/enable` | Code bestätigen und 2FA aktivieren |
| `POST` | `/v1/auth/2fa/disable` | 2FA deaktivieren — erfordert einen Code und dein Passwort |
| `POST` | `/v1/auth/2fa/recovery-codes` | Einen neuen Satz Wiederherstellungscodes ausstellen |
| `POST` | `/v1/auth/2fa/login` | Challenge + Code gegen ein JWT tauschen (kein Auth-Header) |

Jeder Endpunkt außer `/auth/2fa/login` erfordert eine authentifizierte Sitzung.

## Verwandt

- [Login](https://info.pocketalert.app/api/user/login.md) — der erste Schritt des Login-Ablaufs
- [Einführung](https://info.pocketalert.app/intro.md) — Überblick über die Authentifizierung
