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.
Berechtigungen (Scopes)
Beim Erzeugen eines Keys wählst du, welche Funktionen er nutzen darf — wir schränken auf Funktionen ein, nicht auf einzelne Modelle. Standardmäßig sind alle aktiviert; schränke pro Anwendungsfall ein (z. B. ein reiner TTS-Key ohne Chat).
| Scope | Erlaubt | Endpoint |
|---|---|---|
chat | Chat-Completions | POST /v1/chat/completions |
embeddings | Embeddings | POST /v1/embeddings |
rerank | Re-Ranking | POST /v1/rerank |
speech | Text-to-Speech | POST /v1/audio/speech |
transcribe | Speech-to-Text | POST /v1/audio/transcriptions |
mcp | Plattform-MCP-Tools | POST /mcp/mcp |
GET /v1/models braucht keinen speziellen Scope — jeder gültige Key darf den
Katalog lesen. Fehlt einem Key der nötige Scope, antwortet der Endpoint mit
403 (permission_error, Message key lacks <scope> scope). Bestehende Keys
behalten vollen Zugriff; Einschränkung ist eine bewusste Wahl bei der
Erstellung.
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_error | Key existiert, hat aber nicht den nötigen Scope für diesen Endpoint (key lacks <scope> scope). |
| 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.