Authentifizierung¶

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "..."
}

Response: JWT Access-Token + Refresh-Token

{
  "access_token": "eyJ...",
  "refresh_token": "abc123...",
  "token_type": "bearer"
}

Token-Verwendung¶

Alle geschuetzten Endpoints erwarten:

Authorization: Bearer <access_token>

2FA-Methoden¶

TOTP (Authenticator App)¶

# Setup starten
POST /api/v1/auth/totp/setup
# → QR-Code + Secret

# Code verifizieren (aktiviert TOTP)
POST /api/v1/auth/totp/verify
{"code": "123456"}

Telegram 2FA¶

# Setup starten
POST /api/v1/auth/telegram/setup
# → Verification-Code wird an Telegram gesendet

# Status pruefen
GET /api/v1/auth/telegram/status

Unterstuetzte Provider:

GitHub — GET /api/v1/auth/oauth/github/authorize
Google — GET /api/v1/auth/oauth/google/authorize

Flow: Redirect → Provider → Callback → JWT-Token

Mail OAuth2 (XOAUTH2 / OAUTHBEARER)¶

Platform API ist OAuth2 Authorization Server fuer den Mail-Stack (Dovecot/Postfix).

# Mail-Token anfordern (erfordert aktives Mail-Konto)
POST /api/v1/auth/mail-token
Authorization: Bearer <access_token>

# Response: {"access_token": "eyJ...", "expires_in": 3600, "email": "user@example.com"}

Token-Typ: mail_access (60 Min TTL). Wird fuer IMAP/SMTP XOAUTH2/OAUTHBEARER verwendet.

Siehe Mail-Dokumentation fuer Details.

Session-Management¶

# Aktueller User
GET /api/v1/auth/me

# Profil aktualisieren
PUT /api/v1/auth/me

# Token erneuern
POST /api/v1/auth/refresh
{"refresh_token": "abc123..."}

# Logout
POST /api/v1/auth/logout

Passwort-Reset¶

# Reset anfordern
POST /api/v1/auth/forgot-password
{"email": "user@example.com"}

# Neues Passwort setzen
POST /api/v1/auth/reset-password
{"token": "...", "password": "neues-passwort"}