Authentication¶

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

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

Response:JWT Access tokens + Refresh tokens

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

Token use¶

All cut endpoints expect:

Authorization: Bearer <access_token>

2FA methods¶

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

Supported 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 is OAuth2 Authorization Server for the 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 type:mail_access(60 min TTL). Used for IMAP/SMTP XOAUTH2/OAUTHBEARER.

See Mail-Documentfor 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

Password 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"}