Zum Inhalt

Auth-Flow

Schritt 1 — Login

curl -X POST https://deine-domain.tld/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"..."}'

Response (ohne 2FA)

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 86400
}

Response (mit 2FA)

{
  "two_fa_required": true,
  "challenge_token": "tx_..."
}

Der Benutzer hat 2FA aktiv (Authenticator-App oder Passkey). Mit dem challenge_token und dem TOTP-Code weiter:

Schritt 2 — 2FA verifizieren

curl -X POST https://deine-domain.tld/api/v1/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"tx_...","code":"123456"}'

Response

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "expires_in": 86400
}

Bei falschem Code: 401 + attempts_remaining im Body. Nach 5 Fehlversuchen: 429 + Retry-After: 1800.

Schritt 3 — Anfragen mit JWT

curl https://deine-domain.tld/api/v1/hosts \
  -H "Authorization: Bearer eyJhbGc..."

Refresh

curl -X POST https://deine-domain.tld/api/v1/auth/refresh \
  -H "Authorization: Bearer <refresh_token>"

Liefert ein neues access_token (und neues refresh_token). Refresh-Token ist Single-Use.

Logout

curl -X POST https://deine-domain.tld/api/v1/auth/logout \
  -H "Authorization: Bearer <access_token>"

Server invalidiert den Refresh-Token, Frontend wirft den Access-Token weg.

Collector-API-Keys sind kein User-Auth

Collectors authentifizieren sich mit einem eigenen API-Key (X-API-Key-Header, als SHA256-Hash gespeichert), Agents mit einem eigenen Agent-Token (X-Agent-Token-Header). Beide werden ausschließlich vom Receiver für Check-Ergebnis-Uploads akzeptiert — sie sind kein Ersatz für den JWT-Login und funktionieren an keinem /api/v1/-User-Endpoint (Hosts, Profile, Dashboards etc.). Für Scripts/CI, die die User-API ansprechen sollen, bleibt nur der reguläre Login-Flow oben (E-Mail/Passwort → JWT) — ein separates API-Key-Konzept für User gibt es aktuell nicht.

Ein Collector-Key entsteht beim Anlegen eines Collectors (/collectors im Frontend) und wird dort einmalig im Klartext gezeigt; ein Agent-Token entsteht beim Einrichten eines Agents auf einem Host. Beide gehören zu genau einer Ressource (Collector bzw. Host), nicht zu einem User.

Permission-Failures

Bei fehlender Permission:

{
  "detail": {
    "error": "permission_denied",
    "missing": "host.delete"
  }
}

HTTP-Status 403.

Tenant-Scope

JWT enthält tenant_id (eigener Tenant) und tenant_scope (null für Super-Admin, sonst Tenant-UUID).

Cross-Tenant-Anfragen (Super-Admin) optional via Query: ?tenant_id=<uuid>. Ohne Query bekommst du den eigenen Tenant.

Rate-Limits

  • Login/2FA: 10 req/min pro IP
  • Sonstige Endpoints: 600 req/min pro User

Bei Überschreitung: 429 + Retry-After.

Zeit-Sync

JWT exp-Claim setzt voraus, dass Client und Server zeitsynchron sind (Default: 30 s Toleranz). Wenn Server-Zeit falsch (kein NTP), gibt es phantome 401-Fehler.

Anschluss