Zum Inhalt

Auth-Flow

Für Scripts und Automationen gibt es den Bearer-Weg: Login liefert ein Access-Token, das im Authorization-Header mitgeht. Die Web-App selbst nutzt einen eigenen Cookie-Weg (HttpOnly-Cookies plus CSRF-Token) — für eigene Clients ist der Bearer-Weg gedacht.

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":"..."}'

Das Feld heißt email; bei einer Anmeldung über Active Directory / LDAP steht dort der Verzeichnis-Benutzername.

Response (ohne 2FA)

{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 43200,
  "requires_2fa": false
}

Das Access-Token gilt 12 Stunden. Ein separates Refresh-Token gibt es im Bearer-Weg nicht.

Response (mit 2FA)

{
  "requires_2fa": true,
  "two_fa_method": "totp",
  "two_fa_factors": ["totp", "backup_code"],
  "pending_token": "eyJhbGc..."
}

two_fa_factors nennt die zweiten Faktoren, die das Konto tatsächlich eingerichtet hat. Das pending_token gilt 5 Minuten und taugt nur für Schritt 2.

Schritt 2 — 2FA verifizieren

curl -X POST https://deine-domain.tld/api/v1/auth/2fa/verify \
  -H "Authorization: Bearer <pending_token>" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

code nimmt einen TOTP-Code oder einen Backup-Code. Für einen Passkey zuerst POST /api/v1/auth/2fa/webauthn/begin (ebenfalls mit dem pending_token) aufrufen und dann {"method":"webauthn","challenge_id":"…","response":{…}} schicken.

Response

{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 43200
}

Bei falschem Code: 401. Nach 5 Fehlversuchen ist der zweite Faktor 30 Minuten gesperrt: 429 mit Retry-After.

Schritt 3 — Anfragen mit dem Token

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

Verlängern

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

Tauscht ein noch gültiges Access-Token gegen ein neues (wieder 12 Stunden). Die Kette endet an der absoluten Sitzungs-Frist aus Sitzungen — danach 401 und neu anmelden. Ein abgelaufenes Token lässt sich nicht verlängern.

Ein Token wird sofort ungültig, wenn das Konto deaktiviert oder gelöscht wird, sich Rolle oder Tenant-Zuordnung ändern, ein Admin das Passwort zurücksetzt oder der Benutzer selbst sein Passwort ändert bzw. „Überall sonst abmelden" wählt.

Logout

POST /api/v1/auth/logout beendet die Cookie-Sitzung der Web-App. Für Bearer-Clients ist es wirkungslos — das Token einfach verwerfen; es läuft nach spätestens 12 Stunden ab.

Step-Up (heikle Aktionen)

Heikle Aktionen (z. B. Benutzer anlegen, Schlüssel erzeugen, Scripts ändern, Sicherheits-Einstellungen) verlangen eine frische Bestätigung der Identität. Ein frischer Login zählt 15 Minuten lang als Bestätigung; danach antworten solche Endpoints mit 403 und

{"detail": {"code": "STEP_UP_REQUIRED", "message": "...", "ttl_seconds": 900}}

Bestätigen:

curl -X POST https://deine-domain.tld/api/v1/auth/step-up \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"method":"totp","code":"123456"}'

method ist einer der Wege, die GET /api/v1/auth/step-up/status unter methods anbietet (password mit Feld password, totp oder backup_code mit code, webauthn). Die Bestätigung gilt 15 Minuten.

Collector- und Agent-Schlüssel sind keine Benutzer-Anmeldung

Collectors authentifizieren sich mit einem API-Key (X-API-Key-Header, nur als SHA256-Hash gespeichert), Agents mit einem Agent-Token (X-Agent-Token-Header). Beide gelten nur für die Wege, die Collector und Agent selbst brauchen (Ergebnisse einliefern, Konfiguration und Heartbeat) — sie sind kein Ersatz für den Login und funktionieren an keinem Benutzer-Endpoint (Hosts, Profile, Dashboards usw.). Für Scripts/CI, die die Benutzer-API ansprechen, bleibt der Login-Flow oben; persönliche API-Tokens für Benutzer gibt es nicht. Ein eigenes Dienstkonto mit passender Rolle ist der übliche Weg.

Ein Collector-Key entsteht beim Anlegen eines Collectors und wird 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 Benutzer.

Fehlende Berechtigung

Fehlt eine Berechtigung, antwortet der Endpoint mit 403, z. B.:

{"detail": "Insufficient permissions"}

Objekte fremder Tenants antworten mit 404, nicht mit 403.

Tenant-Scope

Das Token trägt Konto, Rolle und Haupt-Tenant. Welche Tenants ein Konto sieht und in welchem Tenant welche Rolle gilt, prüft der Server bei jeder Anfrage aus der aktuellen Zuordnung (siehe Rollen). Listen-Endpoints nehmen meist ?tenant_id=<uuid> als Filter; ohne Filter kommen alle Tenants, auf die das Konto Zugriff hat.

Rate-Limits

  • Login, 2FA-Verifizierung, Passkey-Challenge und Step-Up: 10 Anfragen/Minute je Client-IP
  • Übrige Endpoints: kein eigenes Limit

Bei Überschreitung: 429.

Zeit-Sync

Die Gültigkeit des Tokens hängt an der Server-Uhr. Läuft sie falsch (kein NTP), kommen scheinbar grundlose 401-Fehler.

Anschluss