Authentifizierung
Bearer-Tokens, Org-Scoping, Sicherheit.
Alle API-Calls benötigen einen Bearer-Token im Authorization-Header.
Authorization: Bearer sk-sovr-…API-Key erzeugen
- UI: Settings → API-Keys.
- „Neuer API-Key" klicken, einen Namen vergeben.
- Token wird einmalig im Klartext angezeigt.
- Sofort sicher speichern (Vault, ENV-Variable, Secret-Manager).
Wichtig: Keys werden serverseitig nur als Hash gespeichert. Wer einen Key verliert, muss einen neuen erzeugen — der alte lässt sich nicht wiederherstellen.
Org-Scoping
Jeder Key gehört zu einer Org. Das bedeutet:
- Verbrauch wird der Org belastet (nicht dem User).
- Logs erscheinen unter
Org → Verbrauch. - Wer aus der Org entfernt wird, verliert seine Org-scoped Keys nicht automatisch — sie funktionieren weiter, bis ein Admin sie widerruft. → Bei Offboarding immer alle Keys des ausscheidenden Users widerrufen.
Key widerrufen
Settings → API-Keys → "Widerrufen". Wirkt sofort. Ein widerrufener Key
liefert für jeden Folge-Call:
HTTP/1.1 401 Unauthorized
{ "error": { "type": "invalid_request_error", "message": "invalid api key" } }Fehler-Cases
| Status | error.type | Bedeutung |
|---|---|---|
| 401 | invalid_request_error | Header fehlt, Key ungültig, Key widerrufen. |
| 403 | permission_denied | Key existiert, hat aber keine Rechte (z. B. Modell nicht freigeschaltet). |
| 429 | rate_limit_exceeded | Rate-Limit erreicht. Retry-After-Header beachten. |
| 503 | service_unavailable | Modell-Endpoint kalt + Cold-Start dauert. Retry mit Backoff. |
Best Practices
- Niemals Keys committen.
.gitignoremuss.env*,*.localenthalten. - Niemals Keys clientseitig (Browser, Mobile-App) ausliefern. Immer über Backend-Proxy.
- Niemals Keys in URL-Query-Strings — sie landen in Server-Logs.
- Pro Anwendungsfall ein eigener Key. So lässt sich gezielt widerrufen.
- Rotation alle 90 Tage empfohlen.
CORS
Die API ist nicht für direkte Browser-Calls gedacht. Wer es trotzdem
versucht, bekommt von uns keine Access-Control-Allow-*-Header — der Call
schlägt fehl. Das ist Absicht und schützt vor versehentlichem Schlüssel-Leak.
Für Browser-Apps: eigenen Backend-Proxy aufsetzen, der die Keys serverseitig hält.
OAuth (geplant)
Für Drittanbieter-Apps, die im Namen eines SovrGPT-Users handeln wollen, ist OAuth-2.0-Authorization-Code-Flow für Q4/2026 geplant. Bis dahin nur API-Keys.