Ressourcen · Authentifizierung

Authentifizierung & Scope-Dokumentation

Produktionsreife Anleitung für JWT-/Session-Authentifizierung, API-Schlüssel-Authentifizierung, Scope-Header, Workspace-Kontext und Validierungsregeln.

Zurück zur Dokumentation Zu den Authentifizierungsmethoden springen

Authentifizierungsmethoden

JWT-/Session-Authentifizierung für Anfragen im Benutzerkontext.
API-Schlüssel-Authentifizierung für Service-to-Service- und kontrollierte Integrationen.

Erforderliche Header

Authorization: Bearer [jwt_token] ODER X-API-Key: [api_key]Content-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: nur im Workspace-Scope erforderlich

Scope-Modell

Der Personal-Scope wird im Kontext des authentifizierten Benutzers ausgeführt.
Der Workspace-Scope wird für einen bestimmten Workspace ausgeführt und berücksichtigt rollenbasierte Kontrollen.

Validierungsregeln

Wenn der Scope 'personal' ist, darf X-Workspace-ID nicht angegeben werden.
Wenn der Scope 'workspace' ist, ist X-Workspace-ID erforderlich.
Ungültige oder widersprüchliche Scope-Header geben HTTP 422 zurück.

Beispiel: JWT-Authentifizierung

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [jwt_token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Hello from JWT auth",
    "stream":false
  }'

Beispiel: API-Schlüssel-Authentifizierung

bash

curl -X POST "/api/v1/chat/completions" \
  -H "X-API-Key: [api_key]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -d '{
    "message":"Hello from API key auth",
    "stream":false
  }'

Workspace-Scope

json

{
  "headers": {
    "X-Scope-Type": "workspace",
    "X-Workspace-ID": "[workspace_uuid]"
  },
  "note": "Workspace scope requires workspace id."
}

Personal-Scope

json

{
  "headers": {
    "X-Scope-Type": "personal"
  },
  "note": "Personal scope must not include workspace id."
}

Fehlermodelle

401

Authentifizierung fehlt, abgelaufen oder ungültig.

403

Scope nicht erlaubt oder Rollenbeschränkung im Workspace.

422

Header-/Kontextvalidierung fehlgeschlagen.

429

Ratenlimit für den aktuellen Authentifizierungskontext überschritten.