Zendesk API-Authentifizierung und Scopes: Ein vollständiger Leitfaden für 2026

Wenn Sie eine Integration mit Zendesk erstellen, ist die Authentifizierung Ihre erste Hürde. Wenn Sie es falsch machen, werden Sie Stunden damit verbringen, mysteriöse 403-Fehler zu beheben. Wenn Sie es richtig machen, haben Sie eine sichere, wartungsfreundliche Verbindung, die einfach funktioniert.

Dieser Leitfaden behandelt alles, was Sie über die Zendesk API-Authentifizierung im Jahr 2026 wissen müssen. Wir werden die verschiedenen Authentifizierungsmethoden durchgehen, erklären, wie OAuth-Scopes funktionieren, und Ihnen anhand von funktionierenden Code-Beispielen zeigen, wie Sie sie implementieren können.

Bei eesel AI erstellen wir täglich Integrationen mit Zendesk. Wir haben gesehen, was funktioniert, was kaputt geht und wie man die häufigsten Fallstricke vermeidet, über die Entwickler stolpern.

Die Zendesk API-Authentifizierungsmethoden verstehen

Zendesk bietet drei Möglichkeiten zur Authentifizierung von API-Anfragen, obwohl eine davon ausläuft. Lassen Sie uns Ihre Optionen aufschlüsseln.

Die drei Authentifizierungsoptionen

Die Passwort-Authentifizierung ist veraltet und Zendesk empfiehlt die Migration zu API-Token oder OAuth. Wenn Sie neu anfangen, überspringen Sie Passwörter vollständig.

API-Token-Authentifizierung

API-Token sind die einfachste Option. Es handelt sich um automatisch generierte Passwörter, die Sie im Zendesk Admin Center (Zendesk-Administrationscenter) erstellen.

So funktionieren die Anmeldeinformationen:

{email_address}/token:{api_token}

Zum Beispiel:

jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Wenn Sie diese Zeichenkette Base64-kodieren, sieht Ihr Authorization-Header wie folgt aus:

Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

Oder mit curl:

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Wichtige Einschränkungen, die Sie kennen sollten:

• Sie können bis zu 256 aktive Token haben (2048, wenn Sie bereits 256 überschritten haben)
• Token können jeden Benutzer im Konto imitieren, einschließlich Administratoren
• Keine granularen Berechtigungen: Ein Token hat den gleichen Zugriff wie der Benutzer, der es erstellt hat
• Token laufen nicht ab, es sei denn, Sie widerrufen sie manuell

Quelle: Zendesk Security and Authentication Docs

OAuth Access Token-Authentifizierung

OAuth ist die bessere Wahl für die meisten Integrationen. Es bietet Ihnen eine granulare Kontrolle über die Berechtigungen durch Scopes, und Token sind an bestimmte Benutzer gebunden, anstatt einen breiten Zugriff auf das Konto zu haben.

Der Ablauf funktioniert wie folgt:

1. Ihre App leitet den Benutzer zu Zendesk weiter, um den Zugriff zu autorisieren
2. Der Benutzer erteilt die Erlaubnis und Zendesk sendet einen Autorisierungscode an Ihre App
3. Ihre App tauscht den Code gegen ein Access Token (Zugriffstoken) aus
4. Sie verwenden das Bearer Token in API-Anfragen

So sieht eine Anfrage aus:

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

OAuth unterstützt auch clientseitige API-Anfragen von Browsern aus, was API-Token aufgrund von CORS-Beschränkungen nicht können.

Quelle: Zendesk OAuth Help Documentation

OAuth-Scopes erklärt

Scopes sind das Herzstück der OAuth-Sicherheit. Sie ermöglichen es Ihnen, nur die Berechtigungen anzufordern, die Ihre App tatsächlich benötigt, und folgen dem Prinzip der geringsten Privilegien.

Was sind OAuth-Scopes?

Stellen Sie sich Scopes als Erlaubnisscheine vor. Anstatt vollen Zugriff auf ein Zendesk-Konto zu erhalten, fordern Sie bestimmte Fähigkeiten an. Ein Reporting-Tool benötigt möglicherweise nur Lesezugriff auf Tickets. Ein Sync-Tool benötigt Lese- und Schreibzugriff. Ein Admin-Dashboard benötigt möglicherweise Immitationsrechte, um im Namen von Benutzern zu handeln.

Breite Scopes

Diese gewähren allgemeinen Zugriff auf alle Ressourcen:

• read: Zugriff auf GET-Endpunkte und das Sideloading verwandter Ressourcen
• write: Zugriff auf POST-, PUT- und DELETE-Endpunkte zum Erstellen, Aktualisieren und Löschen
• impersonate: Ermöglicht es Administratoren, Anfragen im Namen von Endbenutzern zu stellen

Ressourcenspezifische Scopes

Für eine feinere Steuerung können Sie Berechtigungen auf bestimmte Ressourcen beschränken:

Einige Ressourcen sind schreibgeschützt: any_channel:write und web_widget:write.

Quelle: Zendesk OAuth Tokens API Reference

Scope-Formatunterschiede (wichtig!)

Hier stolpern Entwickler oft. Zendesk verwendet unterschiedliche Formate, je nachdem, welchen Endpunkt Sie verwenden:

Für die OAuth Tokens API (/api/v2/oauth/tokens):

{
  "token": {
    "client_id": 1234,
    "scopes": ["tickets:read", "users:read"]
  }
}

Für den Autorisierungs-Flow (/oauth/tokens):

{
  "grant_type": "authorization_code",
  "scope": "tickets:read users:read"
}

Das erste verwendet ein Array. Das zweite verwendet eine durch Leerzeichen getrennte Zeichenkette. Wenn Sie diese verwechseln, erhalten Sie verwirrende Fehler.

Implementierung der OAuth-Authentifizierung

Lassen Sie uns die vollständige Implementierung Schritt für Schritt durchgehen.

Schritt 1: Erstellen Sie einen OAuth-Client

Zuerst müssen Sie Ihre Anwendung bei Zendesk registrieren.

1. Navigieren Sie im Zendesk Admin Center zu Apps und Integrationen > APIs > OAuth-Clients

2. Klicken Sie auf OAuth-Client hinzufügen

3. Füllen Sie die Details aus:

   • Name: Ihr App-Name (Benutzer sehen dies bei der Autorisierung)
   • Description: Kurze Erklärung, was Ihre App macht
   • Client kind: Wählen Sie Public (Öffentlich) für mobile/SPA-Apps oder Confidential (Vertraulich) für serverseitige Apps
   • Redirect URLs: Ihre Callback-URLs (muss HTTPS sein, außer für localhost)

4. Klicken Sie auf Speichern

5. Kopieren Sie sofort den Wert Secret. Er wird nur einmal angezeigt.

6. Notieren Sie sich Ihre Unique Identifier (eindeutige Kennung) (dies ist Ihre client_id)

Verständnis der Client-Arten:

• Confidential clients (Vertrauliche Clients) laufen auf sicheren Servern, auf denen Anmeldeinformationen geschützt werden können. Sie können PKCE, Client-Secrets oder beides verwenden.
• Public clients (Öffentliche Clients) laufen in Browsern oder mobilen Apps, in denen Anmeldeinformationen sichtbar sind. Sie müssen PKCE zur Sicherheit verwenden.

Wenn Sie eine serverseitige Integration erstellen, wählen Sie Confidential. Wählen Sie für JavaScript-Apps oder mobile Apps Public.

Quelle: Zendesk OAuth Help Documentation

Schritt 2: Autorisierung anfordern

Senden Sie Ihre Benutzer zur Autorisierungsseite von Zendesk:

https://{subdomain}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  redirect_uri=https://yourapp.com/callback&
  client_id=your_unique_identifier&
  scope=read%20write&
  state=random_state_string

Erforderliche Parameter:

• response_type=code (Sie möchten einen Autorisierungscode zurück)
• redirect_uri (muss mit dem übereinstimmen, was Sie registriert haben)
• client_id (Ihre eindeutige Kennung)
• scope (durch Leerzeichen getrennte Liste von Berechtigungen)

Optional, aber empfohlen:

• state (zufällige Zeichenkette, um CSRF-Angriffe zu verhindern)
• code_challenge und code_challenge_method=S256 (für PKCE)

Der Benutzer sieht eine Autorisierungsseite, auf der er gefragt wird, ob er Ihrer App Zugriff gewähren möchte. Wenn er zustimmt, leitet Zendesk mit einem Autorisierungscode zu Ihrer redirect_uri weiter:

https://yourapp.com/callback?code=7xqwtlf3rrdj8uyeb1yf

Wichtig: Der Autorisierungscode läuft in 120 Sekunden ab. Tauschen Sie ihn umgehend aus.

Schritt 3: Code gegen Access Token austauschen

Stellen Sie eine POST-Anfrage, um den Code auszutauschen:

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "7xqwtlf3rrdj8uyeb1yf",
    "client_id": "your_unique_identifier",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://yourapp.com/callback",
    "scope": "read write",
    "expires_in": 172800,
    "refresh_token_expires_in": 7776000
  }'

Sie erhalten eine Antwort wie:

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope": "read write",
  "expires_in": 172800,
  "refresh_token_expires_in": 7776000
}

Speichern Sie beide Token sicher. Das Access Token wird für API-Aufrufe verwendet. Das Refresh Token (Aktualisierungstoken) verschafft Ihnen ein neues Access Token, wenn das aktuelle abläuft.

Token-Ablauf-Einstellungen:

• expires_in: 300 Sekunden (5 Minuten) bis 172.800 Sekunden (2 Tage)
• refresh_token_expires_in: 604.800 Sekunden (7 Tage) bis 7.776.000 Sekunden (90 Tage)

Quelle: Zendesk OAuth Help Documentation

Schritt 4: Authentifizierte API-Anfragen stellen

Verwenden Sie nun Ihr Access Token:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

Oder in Python:

import requests

headers = {
    "Authorization": f"Bearer {access_token}"
}
response = requests.get(
    "https://yourdomain.zendesk.com/api/v2/tickets.json",
    headers=headers
)

Oder in Node.js:

const axios = require('axios');

const response = await axios.get(
  'https://yourdomain.zendesk.com/api/v2/tickets.json',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`
    }
  }
);

Wenn das Access Token abläuft, verwenden Sie das Refresh Token, um ein neues zu erhalten, ohne dass der Benutzer sich erneut autorisieren muss.

Häufige Scope-Konfigurationen nach Anwendungsfall

Verschiedene Integrationen benötigen unterschiedliche Berechtigungen. Hier sind typische Scope-Konfigurationen für gängige Szenarien.

Read-Only Reporting Tools (Nur-Lese-Reporting-Tools)

Für Dashboards, die Ticketdaten abrufen, ohne Änderungen vorzunehmen:

read

Oder genauer gesagt:

tickets:read users:read organizations:read

Dies gibt Ihrem Tool Zugriff auf die Anzeige von Tickets, Benutzern und Organisationen, ohne die Möglichkeit, etwas zu ändern.

Zwei-Wege-Sync-Integrationen

Für die Synchronisierung von Zendesk mit einem CRM oder anderen Systemen:

tickets:read tickets:write users:read users:write organizations:read organizations:write

Dadurch können Sie vorhandene Daten lesen und Aktualisierungen an Zendesk zurückgeben.

Help Center Content Management (Hilfecenter-Content-Management)

Für Tools, die Wissensdatenbankartikel verwalten:

hc:read hc:write

Dies beschränkt die Berechtigungen nur auf Hilfecenter-Inhalte und hält Tickets und Benutzerdaten außerhalb der Reichweite.

Customer-Facing Portals (Kundenorientierte Portale)

Für eingebettete Widgets, in denen Endbenutzer ihre eigenen Tickets erstellen und anzeigen:

requests:read requests:write impersonate

Der impersonate-Scope ermöglicht es Ihrer App, Tickets im Namen von Endbenutzern zu erstellen, ohne dass diese Zendesk-Konten benötigen.

Fehlerbehebung bei Authentifizierungsfehlern

Auch mit der richtigen Einrichtung geht etwas schief. Hier erfahren Sie, wie Sie die häufigsten Probleme beheben können.

403 Forbidden Errors (403 Verboten-Fehler)

Ein 403 bedeutet, dass Ihr Token gültig ist, Sie aber keine Berechtigung für diese Aktion haben.

Ursachen:

• Fehlender erforderlicher Scope für den Endpunkt
• Falsches Scope-Format (Array vs. Zeichenkette)
• Die Benutzerrolle erlaubt diese Aktion nicht (z. B. versucht ein Agent, nur für Administratoren vorgesehene Endpunkte zu verwenden)

Behebung: Überprüfen Sie die API-Dokumentation für den erforderlichen Scope des Endpunkts. Überprüfen Sie, ob Ihr Token diesen Scope hat, indem Sie den Show Token-Endpunkt verwenden.

401 Unauthorized Errors (401 Unautorisiert-Fehler)

Ein 401 bedeutet, dass Ihr Token ungültig, abgelaufen oder fehlerhaft ist.

Ursachen:

• Token ist abgelaufen (wenn Sie ein Ablaufdatum festgelegt haben)
• Token wurde vom Benutzer oder einem Administrator widerrufen
• Das Token-Format ist falsch (z. B. fehlt das Präfix "Bearer")

Behebung: Aktualisieren Sie das Token, wenn Sie ein Refresh Token haben. Andernfalls leiten Sie den Benutzer erneut durch den Autorisierungs-Flow.

Häufige OAuth-Fehler

Quelle: Zendesk OAuth Help Documentation

Sicherheits-Best Practices für die Zendesk API-Authentifizierung

Die Authentifizierung zum Laufen zu bringen ist der erste Schritt. Sie sicher zu halten, ist ein fortlaufender Prozess.

Token Management (Token-Verwaltung)

• Store tokens encrypted (Token verschlüsselt speichern): Speichern Sie Token niemals im Klartext oder übertragen Sie sie an Code-Repositories
• Implement automatic rotation (Automatische Rotation implementieren): Aktualisieren Sie Token, bevor sie ablaufen, um Dienstunterbrechungen zu vermeiden
• Delete unused tokens (Unbenutzte Token löschen): Widerrufen Sie Token für Integrationen, die Sie nicht mehr verwenden
• Monitor token usage (Token-Nutzung überwachen): Zendesk verfolgt, wann Token verwendet werden. Achten Sie auf unerwartete Aktivitäten

Scope Selection (Scope-Auswahl)

• Request minimal scopes (Minimale Scopes anfordern): Fordern Sie nur Berechtigungen an, die Ihre App tatsächlich benötigt
• Review granted permissions (Erteilte Berechtigungen überprüfen): Überprüfen Sie regelmäßig, welche Scopes Ihre Token haben
• Document scope requirements (Scope-Anforderungen dokumentieren): Führen Sie Aufzeichnungen darüber, warum jeder Scope für die Compliance benötigt wird

Integration Security (Integrationssicherheit)

• Use HTTPS for all requests (HTTPS für alle Anfragen verwenden): Die Zendesk API ist nur über SSL verfügbar und erfordert TLS 1.2
• Implement PKCE for public clients (PKCE für öffentliche Clients implementieren): Erforderlich für mobile und browserbasierte Apps
• Validate state parameters (Statusparameter validieren): Überprüfen Sie immer, ob der Statusparameter mit dem übereinstimmt, was Sie gesendet haben, um CSRF-Angriffe zu verhindern
• Support SNI (SNI unterstützen): Ihr HTTP-Client muss die TLS-Erweiterung Server Name Indication unterstützen

Quelle: Zendesk Security and Authentication Docs

Sichere Zendesk-Integrationen mit eesel AI erstellen

Wenn sich das alles nach viel Aufwand anfühlt, sind Sie nicht allein. Die Authentifizierung ist einer der fehleranfälligsten Teile beim Erstellen von Zendesk-Integrationen.

Bei eesel AI kümmern wir uns sicher um Zendesk OAuth, sodass Sie sich keine Gedanken über Token-Verwaltung, Scope-Konfiguration oder Aktualisierungslogik machen müssen. Unsere Zendesk-Integration wird mit vorkonfigurierten Scopes geliefert, die dem Prinzip der geringsten Privilegien folgen, automatischer Token-Aktualisierung und integrierter Fehlerbehandlung für häufige Authentifizierungsprobleme.

Wir bieten auch einen AI Agent an, der mit Ihren Zendesk-Daten arbeiten kann, um Support-Workflows zu automatisieren. Er verbindet sich über denselben sicheren OAuth-Flow, wobei die Scopes auf genau das beschränkt sind, was die Automatisierung benötigt.

Ob Sie es selbst erstellen oder eine Plattform wie unsere verwenden, der Schlüssel ist, die Authentifizierung von Anfang an richtig zu machen. Eine sichere Grundlage macht alles andere einfacher.

Ob Sie es selbst erstellen oder eine Plattform wie unsere verwenden, der Schlüssel ist, die Authentifizierung von Anfang an richtig zu machen. Eine sichere Grundlage macht alles andere einfacher.