Authentifizierung

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.

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 und GET /v1/me brauchen keinen speziellen Scope — jeder gültige Key darf den Katalog lesen und seine eigenen Rechte abfragen. 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.

Rechte abfragen statt ausprobieren

curl https://sovrgpt.com/api/v1/me -H "Authorization: Bearer $SOVR_KEY"

{
  "object": "api_key",
  "id": "…",
  "org_id": "…",
  "name": "Diktat-Integration",
  "key_prefix": "sovr_a1b2c3d4",
  "expires_at": null,
  "scopes": ["transcribe"],
  "permissions": [
    { "scope": "chat",        "label": "Chat",           "endpoint": "POST /v1/chat/completions",   "granted": false },
    { "scope": "embeddings",  "label": "Embeddings",     "endpoint": "POST /v1/embeddings",         "granted": false },
    { "scope": "rerank",      "label": "Re-Ranking",     "endpoint": "POST /v1/rerank",             "granted": false },
    { "scope": "speech",      "label": "Text-to-Speech", "endpoint": "POST /v1/audio/speech",       "granted": false },
    { "scope": "transcribe",  "label": "Speech-to-Text", "endpoint": "POST /v1/audio/transcriptions","granted": true },
    { "scope": "mcp",         "label": "MCP-Tools",      "endpoint": "POST /mcp/mcp",               "granted": false }
  ]
}

permissions führt alle möglichen Scopes auf, nicht nur die gewährten — sonst müsstest du die möglichen Werte kennen, um zu merken, dass einer fehlt. So steht bei der Einrichtung sofort da: „dieser Schlüssel darf erkennen, aber nicht formatieren."

Die Antwort enthält niemals den Schlüssel-Hash und niemals die Kennung des Menschen, der den Schlüssel angelegt hat. key_prefix ist der dafür vorgesehene Anzeigewert: er erkennt den Schlüssel wieder, ohne ihn zu verraten.

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. .gitignore muss .env*, *.local enthalten.
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.