Authentication

Alle Cortina-Endpoints — außer den Health-Probes /health und /ready — erwarten einen Bearer Token im Authorization-Header.

Header

Authorization: Bearer lissa_live_<64-hex-chars>
Content-Type: application/json

Header	Verpflichtend	Beschreibung
Authorization: Bearer …	Ja	Der API-Key. Format lissa_live_<64-hex>.
Content-Type: application/json	Ja (POST)	Request-Body wird als JSON erwartet.
X-Request-Id	Optional	Eigene Korrelations-ID; wird im Audit-Log mitgeführt.

API-Key-Format

lissa_live_<64-hex-chars>

• Prefix lissa_live_ für Production-Keys.
• 64 Hex-Zeichen Body, kryptographisch zufällig.
• Server-seitig wird nur der mit API_KEY_SALT gesalzene SHA256-Hash gespeichert. Plaintext wird beim Erstellen genau einmal zurückgegeben — verloren = neu erstellen.

Wie man einen Key bekommt

API-Keys werden über das Lissa-AI-Platform-Portal erstellt und verwaltet:

1. Account auf platform.lissa-ai.de/register erstellen.
2. Einloggen, im Dashboard API Keys öffnen und Create API Key wählen.
3. Den Key einmalig kopieren und sicher speichern.
4. Den Key in jedem API-Request als Bearer Token senden.

Authorization: Bearer lissa_live_<dein-key>

Key-Management wie Widerruf, Rotation und neue Keys läuft ebenfalls über platform.lissa-ai.de.

Rate-Limit-Header

Jede Antwort enthält die aktuellen Rate-Limit-Stände:

Header	Bedeutung
X-RateLimit-Limit	Konfiguriertes Limit pro 60-Sekunden-Fenster.
X-RateLimit-Remaining	Verbleibende Requests im aktuellen Fenster.
X-RateLimit-Reset	Unix-Timestamp, wann das Fenster resettet.
Retry-After	Sekunden bis Retry, nur bei 429.

Default-Limit: 60 Requests pro Minute pro Key. Höhere Limits sind per api_keys.rate_limit_per_minute-Override pro Key konfigurierbar.

Error-Responses

Auth- und allgemeine Fehler kommen in einem stabilen { "error": { "code", "message" } }-Format zurück:

HTTP	code	Wann
401	unauthorized	Header fehlt, Token-Format ungültig, oder Key nicht in der DB.
401	key_inactive	Key existiert, aber ist deaktiviert.
403	forbidden	Key existiert + ist aktiv, aber darf den Endpoint nicht aufrufen.
429	rate_limit_exceeded	Rate-Limit überschritten. Retry-After enthält Sekunden bis Reset.

Beispiel-401-Response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

Sicherheits-Notizen

• Speichere den Plaintext-Key nicht in Git. Klingt offensichtlich, ist aber der häufigste Leak-Pfad.
• Rotiere Keys über die Platform. Erstelle einen neuen Key, aktualisiere deine Secrets und widerrufe anschließend den alten Key.
• Per-Tenant-Scoping ist serverseitig. Du kannst keine Daten eines anderen Tenants sehen, selbst wenn du dessen session_id rätst.