Wenn Sie auf der Zendesk Developer Platform aufbauen, sind wahrscheinlich 401- oder 403-Fehler aufgetreten. Diese Statuscodes sind auf viele fehlgeschlagene API-Anfragen zurückzuführen, die wir besonders früh im Lebenszyklus einer Integration sehen.

Beide Fehler betreffen zwar die Zugriffskontrolle, schlagen aber aus unterschiedlichen Gründen fehl und erfordern unterschiedliche Ansätze. Wenn Sie sie als austauschbar betrachten, können Sie oft Zeit verschwenden und wiederholt fehlgeschlagene Anfragen hervorrufen.

In diesem Beitrag erfahren Sie, wie 401- und 403-Fehler in Zendesk funktionieren, wie sie schnell diagnostiziert und anhand praktischer Beispiele und Schritte zur Fehlerbehebung zuverlässig behoben werden 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

Unterschied zwischen 401 und 403

Beide Statuscodes beziehen sich auf die Zugriffskontrolle, schlagen aber in unterschiedlichen Phasen des Anfrageprozesses fehl.

401 Nicht autorisiert

Eine 401-Antwort bedeutet, dass die Zendesk-API die Anfrage nicht authentifizieren kann. Zendesk kann den Anrufer nicht identifizieren und wertet daher keine Berechtigungen oder Geschäftslogik aus.

Häufige Ursachen:

  • Fehlende oder falsch formatierte Autorisierungsheader
  • Falsche Base64-Codierung für Standardauthentifizierung
  • Falsches E-Mail- und Token-Format
  • Abgelaufene oder widerrufene API-Token
  • OAuth Token in einem Standardauthentifizierungsheader
  • Ungültige oder abgelaufene JWTs für Messaging

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

403 Forbidden

Eine 403-Antwort bedeutet, dass Zendesk die Anfrage authentifiziert hat, die authentifizierte Identität aber nicht berechtigt ist, die angeforderte Aktion auszuführen.

Typische Ursachen:

  • OAuth Token ohne erforderliche Zugriffsarten
  • Anmeldedaten von Endbenutzern für Nur-Agent-Endpunkte
  • Zugriff auf Ressourcen einer anderen Marke
  • IP-Zulassungslistenregeln für Konten
  • Gesperrte oder herabgestufte Agentenkonten

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

Schneller Diagnosefluss

Wenn Sie Zugriffsprobleme debuggen, können Sie sie am schnellsten Schritt für Schritt isolieren.

  1. Beginnen Sie mit einem Lockentest. Wenn die curl-Anforderung fehlschlägt, betrifft das Problem wahrscheinlich Anmeldedaten oder die Kontokonfiguration, nicht Ihren Anwendungscode
  2. Bestätigen Sie, dass Sie die richtige Zendesk-Subdomäne anrufen. Die Anmeldedaten beziehen sich auf eine bestimmte Umgebung, und Sandbox und Produktionstoken werden nicht ausgetauscht.
  3. Stellen Sie sicher, dass Sie die richtige Authentifizierungsmethode verwenden. Verwechslungen zwischen Basic Auth, OAuth und JWT führen häufig zu Fehlern.
  4. Überprüfen Sie die Rolle des authentifizierten Benutzers. Viele Endpunkte erfordern Agenten- oder Administratorberechtigungen, auch wenn die Authentifizierung erfolgreich ist
  5. Wenn Sie OAuth verwenden, stellen Sie sicher, dass das Token die für den Endpunkt erforderlichen Zugriffsarten enthält
  6. Überlegen Sie abschließend, wohin die Anfrage führt. Anfragen nach Browser-Ursprung schlagen oft aufgrund von Cross-Origin Resource Sharing (CORS)-Richtlinien fehl, wenn Sie das API-Token Basic-Authentifizierung oder andere nicht unterstützte clientseitige Konversationsflüsse verwenden. Wenn Sie die API von einem Browser aus aufrufen müssen, verwenden Sie einen OAuth Flow, der CORS unterstützt, leiten Sie Anfragen über einen Backend-Service weiter oder verwenden Sie eine Zendesk App mit dem ZAF Client. Weitere Informationen zu CORS-Anfragen finden Sie unter Bereitstellen clientseitiger CORS-Anfragen an die Ticketing API.

Richtig authentifizieren

Die Authentifizierung wird vor jeder Berechtigung oder Geschäftslogikprüfung ausgeführt. 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 Formatregeln.

API-Token-Authentifizierung

API-Token verwenden die Standardauthentifizierung, und der Benutzername muss das Suffix /token enthalten.

Das richtige Format lautet:

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

Ein häufiger Fehler, der einen 401-Fehler zurückgibt, ist das Weglassen des Suffix /token:

emailAddress:APITOKEN

Ein Beispiel für Node.js:

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

Integrationen, die langlebige Anmeldedaten oder detaillierte Berechtigungskontrolle benötigen, verwenden häufig OAuth. OAuth-Zugriffstoken mit dem Bearer-Schema senden. Verwenden Sie diese Kopfzeile:

Authorization: Bearer ACCESS_TOKEN

Beispielanforderung mit curl:

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

Ein Beispiel für Node.js:

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 Nicht autorisiert mit OAuth ist ein gültiges Zugriffstoken, das mit dem falschen Schema gesendet wird. In diesem Fall kann Zendesk die Anfrage nicht authentifizieren und gibt eine 401 zurück, bevor sie Zugriffsarten oder Berechtigungen bewertet.

OAuth Token verwenden auch Bereiche, die zulässige Aktionen definieren. Ein Token kann sich authentifizieren und trotzdem 403 Verboten zurückgeben, wenn es die für den Endpunkt erforderlichen Zugriffsarten nicht aufweist.

Ein Token mit tickets:read kann beispielsweise Ticketdaten abrufen, aber keine Tickets erstellen oder aktualisieren. Ein Schreibversuch ohne den richtigen Bereich gibt immer einen 403-Fehler zurück.

403: You do not have access to this resource

In diesem Fall funktioniert die Authentifizierung, aber Sie müssen das Token mit den richtigen Zugriffsarten neu generieren. Einzelheiten zum Anwendungsbereich finden Sie unter OAuth Tokens for Grant Types (Englisch).

JWT-Authentifizierung für Messaging

Zendesk Messaging in Web- oder mobilen Apps verwendet JWT, um Endbenutzer zu identifizieren. Ihr Backend muss ein JSON Web Token mit dem Geheimnis aus dem Admin Center signieren. Zendesk validiert das Token, bevor es die Messaging-Sitzung mit einem Benutzer verknüpft.

Messaging-JWTs benötigen bestimmte Header- und Claim-Werte, damit Zendesk die Identität des Benutzers auflösen kann.

Ein Messaging-JWT muss mindestens Folgendes enthalten:

  • kid – Schlüssel-ID aus Admin Center im JWT-Header, nicht Nutzlast
  • external_id – Eine eindeutige Kennung für den Benutzer
  • Anwendungsbereich – Der Wert „user“ für die Endbenutzerauthentifizierung in Messaging

Optionale Claims wie Name, E-Mail und email_verified können Benutzerdetails in der Agentenoberfläche enthalten und einen E-Mail-basierten Identitätsabgleich in Support ermöglichen.

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 Ansprüche wie external_id oder scope fehlen oder Sie sich mit dem falschen Geheimnis anmelden, gibt Zendesk 401 Unauthorized zurück.

Häufige 401-Ursachen mit JWT:

  • Ein JWT-Geheimnis aus der falschen Umgebung (Sandbox vs. Production)
  • Ein abgelaufenes Token oder ungültige zeitbasierte Ansprüche
  • Erforderliche Claims wie external_id oder scope sind nicht vorhanden
  • Ein Token, das mit einem falschen oder rotierten Geheimnis signiert ist
  • Falsch formatiertes oder falsch codiertes JWT

Um die Messaging-Authentifizierung zu debuggen, müssen Sie zuerst das richtige Geheimnis und die erforderlichen Claims bestätigen. Wenn die Authentifizierung erfolgreich ist, das Identitätsverhalten aber deaktiviert scheint, überprüfen Sie stabile und einheitliche Werte für external_id und optionale Identitätsfelder in allen Sitzungen. 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 kann.

Falsche Autorisierungsheader, deaktivierte Token oder Umgebungsinkongruenzen verursachen die meisten 401 Antworten.

Format Grundlegende Authentifizierungsheader wie diese:

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

Unerwartete Zeichen, Leerzeichen oder Codierungsprobleme führen oft zu stillen Fehlern.

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

Häufige Ursachen für 403-Fehler

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

Das Fehlen von OAuth-Bereichen verursacht die meisten 403 Antworten. Ein Token mit tickets:read kann beispielsweise Tickets abrufen, aber nicht erstellen oder aktualisieren. Ein Schreibversuch gibt immer einen 403-Fehler zurück.

OAuth-Bereiche können nach der Tokenerstellung nicht mehr geändert werden. Wenn Zugriffsarten falsch sind, generieren Sie ein neues Token.

Ein weiterer häufiger Fallstrick: Anruf an Endpunkte, die nur für Agenten bestimmt sind, mit Endbenutzeranmeldedaten. OAuth Token für Endbenutzer können /Benutzer/mich anrufen, geben aber für beschränkte Endpunkte wie Tickets, Ansichten oder Ticketfelder 403 zurück.

Weitere Ursachen sind widerrufene Token, IP-Zulassungsregeln und Zugriffsbeschränkungen für Multibrand. In diesen Fällen lehnt Zendesk die Anfrage ab, weil Anmeldedaten inaktiv sind oder der Benutzer die Zugriffskriterien nicht erfüllt.

Schrittweise Fehlerbehebung

1. Anmeldedaten isoliert validieren:

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

2. Prüfen Sie die CORS-Limits:

Wenn curl funktioniert, Ihre clientseitige App aber fehlschlägt, treffen Sie wahrscheinlich auf CORS-Beschränkungen. Öffnen Sie die Entwicklerkonsole des Browsers und überprüfen Sie den Fehler. Wenn Sie eine 401/403-Nachricht mit der Access-Control-Allow-Origin-Nachricht sehen, blockiert der Browser die Anfrage, bevor Zendesk sie verarbeiten kann.

3. Rohe Anfragekopfzeilen überprüfen:

  • Autorisierungsheader protokollieren: Drucken Sie die genaue Zeichenfolge, die Ihre App sendet. Stellen Sie sicher, dass kein ausgeblendeter Whitespace und korrekte Präfixe wie Basic oder Bearer vorhanden sind.
  • Umgebung überprüfen: Stellen Sie sicher, dass Ihre App auf die richtige Subdomäne ausgerichtet ist. Viele Teams verwenden eine Sandbox-URL mit Produktionsanmeldedaten, oder umgekehrt.

4. Geltungsbereiche und Ansprüche überprüfen:

  • OAuth: Rufen Sie /api/v2/OAuth/tokens/current auf, um aktuelle Zugriffsarten aufzulisten. Vergewissern Sie sich, dass das Token den Umfang aufweist, den die Ressource benötigt.
  • Für Messaging/JWT: JWT-Nutzlast neu formatieren. Vergewissern Sie sich, dass das Kind (Schlüssel-ID) mit Ihrer Zendesk-Konfiguration übereinstimmt und dass Sie das richtige Signaturgeheimnis verwendet haben.

Zum guten Schluss

Die meisten 401- und 403-Fehler auf der Zendesk Developer Platform sind auf eine kleine Reihe vorhersehbarer Fehlkonfigurationen zurückzuführen. Wenn Sie die Authentifizierung von der Autorisierung trennen, beschleunigen Sie die Diagnose und erhöhen die Zuverlässigkeit.

Validieren Sie Anmeldedaten frühzeitig, bestätigen Sie Zugriffsarten und Rollen und verfolgen Sie einen strukturierten Diagnoseansatz, um Probleme schnell zu lösen und Wiederholungen in der Produktion zu vermeiden.

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