Skip to main content
Alle Public-API-Requests brauchen einen API-Schlüssel im HTTP-Header cx-api-key:
Ohne gültigen Schlüssel erhältst du 401 mit Code API_KEY_REQUIRED oder INVALID_API_KEY.

​
Schlüssel erstellen und verwalten

Schlüssel legst du unter Einstellungen → API an. Jeder Schlüssel gehört zu einer Organisation — mit einem Schlüssel kommst du nicht in einen anderen Workspace.
Benenne Schlüssel nach Zweck (prod-warehouse-sync, staging-ki-agent), damit du bei der Rotation weißt, welche Integration du anpasst.

​
Scopes

Scopes begrenzen, was ein Schlüssel darf. Neue Schlüssel haben standardmäßig nur tickets:read. Fehlt der Scope, kommt 403 mit Code FORBIDDEN_SCOPE.

​
Least Privilege für KI-Agenten

Für reine Lese-Agenten (Tickets listen, Threads lesen, zusammenfassen):
  1. Schlüssel nur mit tickets:read anlegen.
  2. tickets:write und tickets:export nur geben, wenn der Agent Legacy-Schreib-/Export-Endpoints braucht.
  3. Schlüssel mit einem Agenten verknüpfen, wenn die sichtbaren Ansichten den Posteingang-Berechtigungen dieses Agenten entsprechen sollen (siehe unten).

​
Legacy-Schlüssel ohne Scopes

Ältere Schlüssel ohne befüllte scopes-Spalte behalten während des Migrationsfensters vollen Zugriff. Beim Rotieren neue Schlüssel mit expliziten Scopes verwenden.

​
Agent-verknüpfte Schlüssel und Ansichtszugriff

Ist ein API-Schlüssel mit einem Support-Agenten verknüpft:
  • GET /views liefert nur Ansichten, die dieser Agent im Posteingang sieht.
  • GET /tickets?view_id=... liefert 404 VIEW_NOT_FOUND, wenn der Agent die Ansicht nicht sehen darf.
Service-Schlüssel ohne verknüpften Agenten sehen alle Organisations-Ansichten.
Findet deine Integration eine Ansicht nicht, die in der UI existiert, prüfe, ob der Schlüssel agent-verknüpft ist und ob der Agent die Freigaberegeln der Ansicht erfüllt.

​
Sicherheit

  • API-Schlüssel nie in Client-Code, öffentlichen Repos oder Browser-Extensions.
  • Bei Leak sofort rotieren.
  • Getrennte Schlüssel pro Umgebung (Staging vs. Produktion).
  • Scoped Schlüssel statt Legacy-Vollzugriff bevorzugen.

​
Verwandt