Wenn Sie auf der Zendesk Developer Platform aufbauen, sind Sie wahrscheinlich irgendwann auf 401- oder 403-Fehler gestoßen. Diese beiden Statuscodes machen einen Großteil der fehlgeschlagenen API-Anfragen aus, die wir besonders früh im Lebenszyklus einer Integration sehen.

Obwohl beide Fehler mit der Zugriffskontrolle zu tun haben, schlagen sie aus ganz unterschiedlichen Gründen fehl und erfordern unterschiedliche Debugging-Ansätze. Wenn Sie sie als austauschbar behandeln, verlieren Sie oft Zeit und scheitern immer wieder an Anfragen.

In diesem Beitrag erfahren Sie, wie 401- und 403-Fehler in Zendesk funktionieren, wie sie schnell diagnostiziert werden und wie Sie sie anhand praktischer Beispiele und Schritte zur Fehlerbehebung zuverlässig beheben können.

Was Sie lernen werden

Am Ende dieses Posts werden Sie Folgendes verstehen:

  • Unterschied zwischen 401 Unauthorized und 403 Forbidden in Zendesk
  • So authentifizieren Sie API-Token, OAuth-Zugriffstoken und JWTs korrekt
  • Auswirkungen von OAuth Zugriffsarten auf die Autorisierung
  • So diagnostizieren Sie falsch formatierte Kopfzeilen, falsche Subdomänen und abgelaufene Anmeldedaten

 

Überblick über 401 vs. 403

Beide Statuscodes beziehen sich zwar auf die Zugriffskontrolle, schlagen aber in unterschiedlichen Phasen der Anfrageverarbeitung fehl.

401 Nicht autorisiert

Eine 401-Antwort bedeutet, dass die Zendesk-API die Anfrage nicht authentifizieren konnte. Zendesk konnte nicht feststellen, wer der Anrufer ist, und versucht daher nicht, Berechtigungen oder Geschäftslogik zu bewerten.

Häufige Ursachen:

  • Fehlende oder falsch formatierte Autorisierungsheader
  • Falsche Base64-Codierung für Standardauthentifizierung
  • Falsche E-Mail- und Token-Formatierung
  • Abgelaufene oder widerrufene API-Token
  • Verwenden von OAuth Token in einer Standard-Auth-Kopfzeile
  • Ungültige oder abgelaufene JWTs für Messaging

Wenn Sie einen 401-Fehler erhalten, konzentrieren Sie sich zuerst darauf, wie die Anforderung authentifiziert wird, und nicht darauf, was sie zu tun versucht.

403 Forbidden

Eine 403-Antwort bedeutet, dass die Anfrage erfolgreich authentifiziert wurde, die authentifizierte Identität aber nicht zur Ausführung der angeforderten Aktion berechtigt ist.

Typische Ursachen:

  • OAuth Token fehlen erforderliche Zugriffsarten
  • Verwenden der Anmeldedaten von Endbenutzern zum Anrufen von Nur-Agent-Endpunkten
  • Zugriff auf Ressourcen einer anderen Marke
  • IP-Beschränkungen für das Konto aktiviert
  • Gesperrte oder herabgestufte Agentenkonten

Wenn Sie einen 403-Fehler erhalten, funktioniert die Authentifizierung korrekt. Das Problem ist die Autorisierung.

 

Schneller Diagnosefluss

Beim Debuggen von Zugriffsproblemen können Sie das Problem am schnellsten Schritt für Schritt isolieren.

Testen Sie Ihre Anfrage zunächst mit curl. Wenn die curl-Anforderung fehlschlägt, liegt das Problem wahrscheinlich an den Anmeldedaten oder der Kontokonfiguration, nicht am Anwendungscode.

Bestätigen Sie als Nächstes, dass Sie die richtige Zendesk-Subdomäne anrufen. Anmeldedaten sind auf eine bestimmte Umgebung beschränkt, und Sandbox und Produktionstoken können nicht ausgetauscht werden.

Stellen Sie dann sicher, dass Sie die richtige Authentifizierungsmethode verwenden. Eine häufige Fehlerquelle ist das Mischen von Basic Auth, OAuth und JWT.

Überprüfen Sie die Rolle des authentifizierten Benutzers. Viele Endpunkte erfordern Agenten- oder Administratorberechtigungen, auch wenn die Authentifizierung erfolgreich ist.

Wenn Sie OAuth verwenden, stellen Sie sicher, dass das Token die für den Endpunkt erforderlichen Zugriffsarten enthält.

Überlegen Sie abschließend, wo die Anfrage ausgeführt wird. Anfragen Browser-Ursprungs werden häufig durch Cross Browser Resource Sharing (CORS)-Richtlinien blockiert, wenn API-Token Basic Auth oder andere nicht unterstützte clientseitige Konversationsflüsse verwendet werden. Wenn Sie die API von einem Browser aus aufrufen müssen, verwenden Sie einen OAuth Flow, der CORS unterstützt, oder leiten Sie Anfragen über einen Backend-Service oder eine Zendesk App mit dem ZAF Client weiter. Weitere Informationen zu CORS-Anforderungen finden Sie unter Bereitstellen clientseitiger CORS-Anforderungen an die Ticketing API. 

 

Korrekte Authentifizierung

Die Authentifizierung erfolgt vor jeder Berechtigung oder Geschäftslogikprüfung. Wenn die Authentifizierung fehlschlägt, kann Zendesk die Anforderung nicht mit einem Benutzer oder einer Integration verknüpfen und gibt einen 401-Fehler zurück.

Zendesk unterstützt mehrere Authentifizierungsmethoden mit jeweils strengen Formatierungsanforderungen.

API-Token-Authentifizierung

API-Token verwenden die Standardauthentifizierung, wobei der Benutzername das Suffix /token enthält.

Das richtige Format lautet:

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

Ein häufiger Fehler, der zu einem 401-Fehler führt, ist das Weglassen des Suffix /token:

emailAddress:APITOKEN

In Node.js sieht ein Arbeitsbeispiel wie folgt aus:

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

 

OAuth-Authentifizierung

OAuth-Zugriffstoken werden häufig für Integrationen verwendet, die langlebige Anmeldedaten oder detaillierte Berechtigungskontrolle erfordern. OAuth Token müssen nach dem Schema der Bearer-Authentifizierung gesendet werden. Das richtige Kopfzeilenformat lautet:

Authorization: Bearer ACCESS_TOKEN

Beispielanforderung mit curl:

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

In Node.js sieht ein Arbeitsbeispiel wie folgt aus:

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

Eine häufige Ursache für 401 Unautorisierte Fehler bei Verwendung von OAuth ist das Senden eines gültigen Zugriffstokens mit dem falschen Authentifizierungsschema. In diesem Fall kann Zendesk die Anfrage nicht authentifizieren und gibt eine 401 zurück, bevor die Zugriffsarten oder Berechtigungen bewertet werden.

OAuth Token führen auch das Konzept der Scopes ein, die ausdrücklich festlegen, welche Aktionen das Token ausführen darf. Ein Token kann sich zwar erfolgreich authentifizieren, gibt aber trotzdem eine 403-verbotene Antwort zurück, wenn es nicht die vom aufgerufenen Endpunkt benötigten Zugriffsarten aufweist.

Ein Token mit tickets:read kann beispielsweise Ticketdaten abrufen, aber keine Tickets erstellen oder aktualisieren. Wenn Sie versuchen, einen Schreibvorgang ohne den entsprechenden Bereich durchzuführen, tritt immer ein 403-Fehler auf. 

403: You do not have access to this resource

In diesem Fall funktioniert die Authentifizierung wie erwartet, aber das Token muss mit den richtigen Zugriffsarten neu generiert werden. Weitere Informationen zu Zugriffsarten finden Sie unter OAuth Tokens for Grant Types (Englisch).

 

JWT-Authentifizierung für Messaging

Bei der Implementierung von Zendesk Messaging in Web- oder mobilen Anwendungen wird die JWT-Authentifizierung verwendet, um Endbenutzer sicher zu identifizieren. In diesem Modell ist Ihr Backend für das Generieren und Signieren eines JSON Web Tokens (JWT) mit dem im Admin Center konfigurierten Geheimnis verantwortlich. Zendesk validiert das Token, bevor die Messaging-Sitzung mit einem Benutzer verknüpft werden kann.

Im Gegensatz zu API-Token oder OAuth benötigen Messaging-JWTs bestimmte Claims und Header-Informationen, damit Zendesk die Identität des Benutzers korrekt auflösen kann.

Ein Messaging-JWT muss mindestens Folgendes enthalten:

  • kid – Schlüssel-ID aus dem Zendesk Admin Center. Dieser Wert muss im JWT-Header enthalten sein, nicht in der Nutzlast.
  • external_id – Eine eindeutige Kennung für den Benutzer. Zendesk verwendet diesen Wert als Primärschlüssel beim Abgleichen oder Erstellen von Benutzerdatensätzen.
  • Bereich – Muss auf „Benutzer“ gesetzt werden, was bedeutet, dass das Token für die Endbenutzerauthentifizierung in Messaging bestimmt ist.

Weitere Angaben wie Name, E-Mail und email_verified sind optional und können zum Ausfüllen von Benutzerdetails in der Agentenoberfläche oder zum E-Mail-basierten Identitätsabgleich in Support hinzugefügt werden.


Beispiel: JWT-Generator Node.js: 

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
	keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

Wenn erforderliche Claims wie external_id oder scope fehlen oder das Token mit dem falschen Geheimnis signiert ist, gibt Zendesk eine 401 Unauthorized-Antwort zurück.


Häufige Ursachen für 401-Fehler im Zusammenhang mit JWT:

  • Verwenden eines JWT-Geheimnisses aus der falschen Umgebung (Sandbox vs. Production)
  • Senden eines abgelaufenen Tokens oder eines Tokens mit ungültigen zeitbasierten Ansprüchen
  • Weglassen erforderlicher Claims wie external_id oder scope 
  • Signieren des Tokens mit einem falschen oder rotierten Geheimnis
  • Senden eines falsch formatierten oder falsch codierten JWT

Stellen Sie beim Debuggen von Problemen mit der Messaging-Authentifizierung zunächst sicher, dass das Token mit dem richtigen Geheimnis signiert ist und die erforderlichen Claims enthält. Wenn die Authentifizierung erfolgreich ist, das Verhalten der Benutzeridentität aber unerwartet ist, überprüfen Sie die Werte für external_id und optionale Identitätsfelder, um sicherzustellen, dass sie stabil und sitzungsübergreifend einheitlich sind. Weitere Informationen finden Sie unter Authentifizierung von Benutzern in Ihrer Anwendung.
 

Häufige Ursachen für 401-Fehler

Eine 401-Antwort bedeutet, dass Zendesk die Anfrage nicht authentifizieren und die Identität des Anrufers nicht ermitteln konnte.

Dies wird in der Regel durch falsch erstellte Autorisierungsheader, deaktivierte Token oder Umgebungsinkongruenzen verursacht.

Standardauthentifizierungsheader müssen wie folgt formatiert sein:

headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
}

Unerwartete Zeichen, Leerzeichen oder Codierungsprobleme führen häufig zu stillen Fehlern.

Denken Sie daran, dass die Zendesk REST-API die Browser-Ursprungsauthentifizierung nicht Support. Clientseitige JavaScript-Anfragen schlagen aufgrund von CORS, fehlenden Sitzungscookies und nicht unterstützten Authentifizierungsflüssen fehl. Verwenden Sie stattdessen einen Backend-Service oder eine mit dem ZAF Client erstellte Zendesk-App.

 

Häufige Ursachen für 403-Fehler

Eine 403-Antwort gibt an, dass Zendesk die Anfrage authentifiziert, aber aufgrund von Berechtigungsregeln den Zugriff verweigert hat.

Die häufigste Ursache sind fehlende OAuth-Bereiche. Ein Token mit ticket:read kann beispielsweise Tickets abrufen, aber nicht erstellen oder aktualisieren. Schreibversuche geben immer einen 403-Fehler zurück.

OAuth Zugriffsarten können nach der Tokenerstellung nicht mehr geändert werden. Wenn Zugriffsarten falsch sind, muss ein neues Token generiert werden.

Eine weitere häufige Verwirrung besteht darin, dass versucht wird, Endpunkte nur für Agenten mit Anmeldedaten für Endbenutzer anzurufen. OAuth Token für Endbenutzer können für /Benutzer/mich funktionieren, geben aber 403 zurück, wenn sie beschränkte Endpunkte wie Tickets, Ansichten oder Ticketfelder aufrufen.

Weitere häufige Ursachen sind widerrufene Token, IP-Zulassungsbeschränkungen und Zugriffsbeschränkungen für mehrere Marken. In diesen Fällen wird die Anfrage abgewiesen, entweder weil die Anmeldedaten nicht mehr aktiv sind oder weil der Benutzer bestimmte Zugriffskriterien nicht erfüllt.

 

Schrittweise Fehlerbehebung

1. Anmeldedaten isoliert validieren Entfernen Sie im Zweifelsfall zunächst den Anwendungscode aus der Gleichung. Validieren Sie Ihre Anmeldedaten mit curl:

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"
  • Wenn dies fehlschlägt: Das Problem ist wahrscheinlich ein Anmeldedaten- oder Kontoproblem.
  • Wenn dies gelingt: Die Anmeldedaten sind gültig. Das Problem liegt in der Anwendungslogik oder -umgebung. Fahren Sie mit Schritt 2 fort.

2. Überprüfen Sie auf CORS-Beschränkungen: Wenn der Befehl curl funktioniert, Ihre clientseitige Anwendung aber fehlschlägt, treffen Sie wahrscheinlich auf CORS-Beschränkungen.

Öffnen Sie die Entwicklerkonsole Ihres Browsers und überprüfen Sie den Fehler. Wenn Sie einen 401/403-Fehler zusammen mit einer Konsolenmeldung zur Access-Control-Allow-Origin sehen, blockiert der Browser die Anfrage, bevor Zendesk sie verarbeiten kann.

3. Untersuchen Sie die rohen Anfrageheader, wenn Sie serverseitigen Code (Node.js, Python, PHP usw.) verwenden und weiterhin Probleme haben:

  • Autorisierungsheader protokollieren: Drucken Sie die genaue Zeichenfolge, die Ihre Anwendung sendet. Stellen Sie sicher, dass es keine versteckten Leerzeichen oder falschen Präfixe gibt (z. B. um sicherzustellen, dass Basic vs. Bearer korrekt verwendet wird).
  • Umgebung überprüfen: Stellen Sie sicher, dass Ihre Anwendung die richtige Subdomäne anspricht. Häufig wird versehentlich eine Sandbox URL mit Produktionsanmeldedaten anvisiert oder umgekehrt.

4. Geltungsbereich und Ansprüche überprüfen Wenn die Authentifizierung erfolgreich ist, Sie aber ein 403-Verbot erhalten, fehlen Ihrem Token möglicherweise die erforderlichen Berechtigungen.

  • OAuth: Überprüfen Sie Ihre aktuellen Zugriffsarten durch Aufruf des Endpunkts /api/v2/OAuth/tokens/current. Stellen Sie sicher, dass das Token den Umfang aufweist, der für die Ressource erforderlich ist, auf die Sie zugreifen möchten.

  • Für Messaging/JWT: JWT-Nutzlast neu formatieren. Stellen Sie sicher, dass das Kind (Schlüssel-ID) mit Ihrer Zendesk-Konfiguration übereinstimmt und dass das zum Generieren des Tokens verwendete Signaturgeheimnis korrekt ist.

     

Zum guten Schluss

Die meisten 401- und 403-Fehler auf der Zendesk Developer Platform sind auf eine kleine Anzahl vorhersehbarer Fehlkonfigurationen zurückzuführen. Sobald Sie Authentifizierungsfehler klar von Autorisierungsfehlern trennen, wird das Debuggen deutlich schneller und zuverlässiger.

Durch frühzeitiges Validieren von Anmeldedaten, Bestätigen von Zugriffsbereichen und Rollen und durch einen strukturierten Diagnoseansatz können Sie diese Probleme rasch lösen und verhindern, dass sie in der Produktion erneut auftreten.

Weitere Informationen finden Sie in der Zendesk-Dokumentation zu API-Tokenzugriff, OAuth Authentifizierung, Zendesk App Framework und Messaging JWT Authentifizierung.

Hinweis zur Übersetzung: Dieser Beitrag wurde mit automatischer Übersetzungssoftware übersetzt, um dem Leser ein grundlegendes Verständnis des Inhalts zu vermitteln. Trotz angemessener Bemühungen, eine akkurate Übersetzung bereitzustellen, kann Zendesk keine Garantie für die Genauigkeit übernehmen.

Sollten in Bezug auf die Genauigkeit der Informationen im übersetzten Beitrag Fragen auftreten, beziehen Sie sich bitte auf die englische Version des Beitrags, die als offizielle Version gilt.

Powered by Zendesk