Authentifizierung

Jede API-Anfrage wird mit einem API-Token authentifiziert. Ein Token handelt als das Teammitglied, dem er gehört: Er sieht und ändert genau das, was diese Person im Agent-Workspace darf, zusätzlich eingeschränkt durch den Scope des Tokens.

Einen Token erstellen

1. Öffnen Sie Admin Center, Integrations, API tokens.
2. Wählen Sie New token, geben Sie ihm einen Namen, der sagt, was ihn nutzt (zum Beispiel „Billing sync“), und wählen Sie einen Scope.
3. Kopieren Sie den Token. Er beginnt mit desk_ und wird nur einmal angezeigt.

Scope	Erlaubt
read	Nur GET-Anfragen
write	Jede Methode: GET, POST, PUT, PATCH, DELETE

Erstellen Sie für jede Integration einen eigenen Token, wenn möglich im Besitz eines eigenen Integrationsnutzers. Ein Widerruf trifft dann nur diese Integration.

Den Token senden

GET /api/tickets HTTP/1.1
Host: yourcompany.chaosdesk.io
Authorization: Bearer desk_xxxxxxxxxxxxxxxxxxxx
Accept: application/json

Antworten sind je nach Accept-Header JSON (application/json) oder JSON-LD (application/ld+json). Teilaktualisierungen nutzen PATCH mit Content-Type: application/merge-patch+json.

Fehler

Status	Bedeutung
401	Token fehlt, ist ungültig, abgelaufen oder widerrufen
402	Die Funktion ist nicht Teil Ihres Plans (plan_required)
403	Der Token-Besitzer darf das nicht, oder ein read-Token wollte schreiben
422	Validierung fehlgeschlagen; der Body listet die Felder
429	Ratenlimit erreicht, siehe Ratenlimits

Fehler nutzen RFC 9457 Problem Details (application/problem+json).

Zendesk-kompatible API

Die Zendesk-kompatible API akzeptiert dieselben Tokens mit den Zendesk-Authentifizierungsarten: Basic Auth mit {email}/token:{token}, ein Bearer-Token oder OAuth Client Credentials.