Authentifizierung und API-Schlüssel

Jeder API-Aufruf braucht einen API-Schlüssel als Bearer-Token im Authorization-Header. Schlüssel gehören zu einer Organisation und lassen sich je Funktion einschränken.

Authorization: Bearer sov_…

API-Schlüssel erzeugen

1. Einstellungen → API-Keys öffnen.
2. Eine Beschreibung eingeben, die Scopes wählen (ab Werk alle angehakt) und „+ Neuen Key erzeugen“ klicken.
3. Der Schlüssel (sov_ plus 48 Hex-Zeichen) erscheint einmalig im Klartext. Legen Sie ihn sofort sicher ab (Vault, Umgebungsvariable, Secret-Manager).

Wir speichern nur einen Hash. Einen verlorenen Schlüssel können wir nicht wiederherstellen; erzeugen Sie dann einen neuen.

Berechtigungen (Scopes)

Scopes schränken Funktionen ein, nicht einzelne Modelle. Legen Sie je Anwendungsfall einen passenden Schlüssel an, zum Beispiel einen reinen Text-to-Speech-Schlüssel ohne Chat.

Ohne Scope, nur mit gültigem Schlüssel: GET /v1/models, GET /v1/me, GET /v1/audio/voices, GET /v1/audio/voices/design-options, GET /v1/decisions/presets und GET /v1/decisions/models.

Fehlt einem Schlüssel der nötige Scope, antwortet der Endpunkt mit 403 (permission_error, Meldung key lacks <scope> scope). Ältere Schlüssel, die nie eingeschränkt wurden, haben alle sieben Scopes.

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": "sov_a1b2c3d4",
  "created_at": "2026-09-01T08:00:00.000Z",
  "last_used_at": null,
  "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 },
    { "scope": "decisions",   "label": "Decision Engine","endpoint": "POST /v1/decisions",          "granted": false }
  ]
}

permissions führt alle Scopes auf, auch die nicht gewährten. So sehen Sie bei der Einrichtung sofort, was fehlt, etwa: „dieser Schlüssel darf transkribieren, aber nicht chatten“. expires_at: null heißt unbefristet.

Die Antwort enthält nie den Schlüssel-Hash und nie die Kennung der Person, die den Schlüssel angelegt hat. key_prefix (die ersten zwölf Zeichen) macht den Schlüssel wiedererkennbar, ohne ihn zu verraten.

Schlüssel und Organisation

Jeder Schlüssel gehört zu einer Organisation:

• Der Verbrauch wird der Organisation berechnet, nicht der Person. Ausgabenlimits je Person gelten für die Person, die den Schlüssel angelegt hat.
• Den Verbrauch sehen Sie unter Einstellungen → Verbrauch.
• Wer die Organisation verlässt, dessen Schlüssel funktionieren weiter, bis ein Admin sie widerruft. Widerrufen Sie beim Offboarding deshalb alle Schlüssel der Person.

Schlüssel widerrufen

Einstellungen → API-Keys → „Widerrufen“. Das wirkt sofort. Jeder weitere Aufruf mit dem Schlüssel bekommt:

HTTP/1.1 401 Unauthorized
{ "error": { "type": "invalid_request_error", "message": "invalid api key" } }

Fehlercodes

Empfehlungen

• Schlüssel nie committen. .gitignore sollte .env* und *.local enthalten.
• Schlüssel nie im Client (Browser, Mobile-App) ausliefern, sondern über ein eigenes Backend.
• Schlüssel nie in URL-Parameter schreiben; dort landen sie in Server-Logs.
• Je Anwendungsfall ein eigener Schlüssel, damit Sie gezielt widerrufen können.
• Schlüssel alle 90 Tage erneuern.

CORS

Die API ist nicht für direkte Aufrufe aus dem Browser gedacht. Sie sendet keine Access-Control-Allow-*-Header, solche Aufrufe schlagen also fehl. Das ist Absicht und schützt davor, dass ein Schlüssel im Browser landet. Für Browser-Apps brauchen Sie einen eigenen Backend-Proxy, der den Schlüssel serverseitig hält.

OAuth (geplant)

Für Drittanbieter-Apps, die im Namen einer Person handeln, ist ein OAuth-2.0-Authorization-Code-Flow für Q4/2026 geplant. Bis dahin gibt es nur API-Schlüssel.