Zum Inhalt springen

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

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 ​

Skripte laufen weiter

2FA gilt für interaktive Logins. API-Schlüssel aus API-Schlüssel 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 ​

MethodeEndpunktZweck
GET/v1/auth/2fa/statusOb 2FA aktiviert ist und wie viele Wiederherstellungscodes noch übrig sind
POST/v1/auth/2fa/setupRegistrierung starten — gibt Schlüssel und QR-Daten zurück
POST/v1/auth/2fa/enableCode bestätigen und 2FA aktivieren
POST/v1/auth/2fa/disable2FA deaktivieren — erfordert einen Code und dein Passwort
POST/v1/auth/2fa/recovery-codesEinen neuen Satz Wiederherstellungscodes ausstellen
POST/v1/auth/2fa/loginChallenge + Code gegen ein JWT tauschen (kein Auth-Header)

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

Verwandt ​

  • Login — der erste Schritt des Login-Ablaufs
  • Einführung — Überblick über die Authentifizierung

Pocket Alert Dokumentation