Authentication

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

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

Header	Verpflichtend	Beschreibung
`Authorization: Bearer …`	Ja	Der API-Key. Format `tup_<env>_<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

tup_live_<64-hex-chars>

Prefix tup_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.

Aktuell auf direkte Anfrage: [email protected] mit gewünschtem Tenant-Namen und Rate-Limit.

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.

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

Speichere den Plaintext-Key nicht in Git. Klingt offensichtlich, ist aber der häufigste Leak-Pfad.
Rotiere den Key über das CLI (scripts/create_api_key.py im Service-Repo) und disable den alten Key in derselben Coolify-Session.
Per-Tenant-Scoping ist serverseitig. Du kannst keine Daten eines anderen Tenants sehen, selbst wenn du dessen session_id rätst.