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, scheitern aber aus unterschiedlichen Gründen und erfordern unterschiedliche Ansätze. Wenn Sie sie als austauschbar behandeln, können Sie oft Zeit verschwenden und wiederholt fehlgeschlagene Anfragen hervorrufen.

Was Sie lernen werden

Am Ende dieses Posts werden Sie Folgendes verstehen:

  • Der Unterschied zwischen 401 Unauthorized- und 403 Forbidden-Fehlern in Zendesk
  • Schnelle Fehlerdiagnose
  • Korrekte Authentifizierung mit API-Token, OAuth Zugriffstoken und JWTs (JSON Web Token)
  • Wie sich OAuth Zugriffsarten auf die Autorisierung auswirken
  • So diagnostizieren Sie falsch formatierte Header, falsche Subdomänen und abgelaufene Anmeldedaten
  • So beheben Sie die Fehler mit Zuversicht durch praktische Beispiele und Schritte zur Fehlerbehebung

Unterschied zwischen 401- und 403-Fehlern

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

401 Unauthorized

Eine 401-Antwort bedeutet, dass die Zendesk-API die Anfrage nicht authentifizieren kann. Zendesk kann den Anrufer nicht identifizieren und wertet daher weder Berechtigungen noch 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 Anfrage authentifiziert, nicht darauf, was die Anfrage 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 für Endbenutzer gegenüber Nur-Agent-Endpunkten
  • 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, ist es am schnellsten, das Problem Schritt für Schritt zu isolieren.

  1. Beginnen Sie mit einem Curl-Test. Wenn die curl-Anforderung fehlschlägt, betrifft das Problem wahrscheinlich Anmeldedaten oder Kontokonfiguration, nicht Ihren Anwendungscode
  2. Bestätigen Sie, dass Sie die richtige Zendesk-Subdomäne anrufen. Die Anmeldedaten beziehen sich auf eine bestimmte Umgebung, 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. Browser-Ursprungsanfragen schlagen häufig an Cross-Origin Resource Sharing (CORS)-Richtlinien fehl, wenn Sie 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.

Korrekte Authentifizierung

Die Authentifizierung erfolgt vor jeder Berechtigung oder Geschäftslogikprüfung. Wenn die Authentifizierung fehlschlägt, kann Zendesk die Anfrage 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 Node.js-Beispiel:

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 diesen Header:

Authorization: Bearer ACCESS_TOKEN

Beispielanfrage mit curl:

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

Ein Node.js-Beispiel:

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 Token für Gewährungsarten.

Verwenden der JWT-Authentifizierung für Messaging

Zendesk Messaging in Web- oder mobilen Apps verwendet JWT zur Identifizierung von Endbenutzern. 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 den E-Mail-basierten Identitätsabgleich in Support ermöglichen.

Beispiel: Node.js JWT-Generator:

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 Sie sich mit dem falschen Geheimnis anmelden, gibt Zendesk 401 Unauthorized zurück.

Häufige 401-Ursachen bei 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 signiert mit einem falschen oder rotierten Geheimnis
  • Ein falsch formatiertes oder falsch codiertes JWT

Um die Messaging-Authentifizierung zu debuggen, müssen Sie zuerst das richtige Geheimnis und die erforderlichen Ansprüche bestätigen. Wenn die Authentifizierung erfolgreich ist, aber das Identitätsverhalten 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 Authenticating users in your application.

Häufige Ursachen für 401-Fehler

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

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

Format Grundlegende Authentifizierungsheader wie folgt:

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 bedeutet, dass Zendesk die Anfrage authentifiziert hat, aber Berechtigungsregeln 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 Nur-Agent-Endpunkte mit Endbenutzeranmeldedaten. OAuth Token für Endbenutzer können /Benutzer/mich anrufen, geben aber 403 für beschränkte Endpunkte wie Tickets, Ansichten oder Ticketfelder 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 die 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 Ihrer Anwendungslogik oder Umgebung. Fahren Sie mit Schritt 2 fort.

2. Auf CORS-Limits prüfen:

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

3. Rohe Anfragekopfzeilen prüfen:

  • Autorisierungsheader protokollieren: Drucken Sie die genaue Zeichenfolge, die Ihre App sendet. Bestätigen Sie keinen ausgeblendeten Whitespace und korrigieren Sie Präfixe wie Basic oder Bearer.
  • Umgebung bestätigen: Bestätigen Sie, dass Ihre App auf die richtige Subdomäne abzielt. Viele Teams verwenden eine Sandbox URL mit Produktionsanmeldedaten, oder umgekehrt.

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

  • Für OAuth: Rufen Sie /api/v2/OAuth/tokens/current auf, um aktuelle Zugriffsarten aufzulisten. Vergewissern Sie sich, dass das Token den für die Ressource erforderlichen Umfang aufweist.
  • 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 kleine vorhersehbare Fehlkonfigurationen zurückzuführen. Trennen Sie die Authentifizierung von der Autorisierung, um die Diagnose zu beschleunigen und die Zuverlässigkeit zu erhöhen.

Validieren Sie Ihre 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