{
"title": "Zendesk API OAuth Scopes: Eine vollständige Entwickleranleitung",
"slug": "zendesk-api-oauth-scopes",
"locale": "de",
"date": "2026-02-27",
"updated": "2026-02-27",
"template": "default",
"excerpt": "Ein praktischer Leitfaden zum Verständnis und zur Implementierung von Zendesk API OAuth Scopes für eine sichere API-Authentifizierung.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"OAuth",
"API",
"Authentication",
"Developer"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Zendesk API OAuth Scopes: Eine vollständige Entwickleranleitung",
"description": "Ein praktischer Leitfaden zum Verständnis und zur Implementierung von Zendesk API OAuth Scopes für eine sichere API-Authentifizierung.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-fe924143-49fd-4326-8dbb-4c8b727a954a"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-fe924143-49fd-4326-8dbb-4c8b727a954a",
"coverImageAlt": "Bannerbild für Zendesk API OAuth Scopes: Eine vollständige Entwickleranleitung",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Häufig gestellte Fragen",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Kann ich Scopes auf einem bestehenden Token ändern?",
"answer": "Nein. Sie können Scopes auf einem bestehenden Token nicht ändern. Um Berechtigungen zu ändern, müssen Sie ein neues Token mit den aktualisierten Scopes generieren, indem Sie den Benutzer erneut durch den Autorisierungsablauf schicken."
},
{
"question": "Was ist der Unterschied zwischen OAuth Scopes und Benutzerrollen in Zendesk?",
"answer": "OAuth Scopes steuern, auf welche API-Endpunkte ein Token zugreifen kann. Benutzerrollen (Administrator, Agent, Endbenutzer) steuern, welche Aktionen ein Benutzer in Zendesk ausführen kann. Die effektiven Berechtigungen eines Tokens sind die Schnittmenge seiner Scopes und der Rolle des autorisierenden Benutzers. Ein Agent kann auch mit breiten OAuth Scopes keine Administratoraktionen ausführen."
},
{
"question": "Woher weiß ich, welche Scopes ein Endpunkt benötigt?",
"answer": "Überprüfen Sie die Zendesk API-Dokumentation. Die meisten Endpunktbeschreibungen enthalten den erforderlichen Scope. Im Allgemeinen benötigen GET-Endpunkte 'read' oder 'resource:read', während POST/PUT/DELETE-Endpunkte 'write' oder 'resource:write' benötigen."
},
{
"question": "Kann ich OAuth Scopes mit API-Token verwenden?",
"answer": "Nein. API-Token sind ein anderer Authentifizierungsmechanismus, der einen breiten Kontozugriff ohne Scope-Einschränkungen gewährt. OAuth-Token verwenden Scopes. Wählen Sie OAuth für granulare Berechtigungen und API-Token für einfache Skripte, bei denen keine Scope-Kontrolle erforderlich ist."
},
{
"question": "Was passiert, wenn ich einen Scope anfordere, der nicht existiert?",
"answer": "Zendesk stellt ein Token aus, aber API-Aufrufe geben 'Forbidden'-Fehler zurück. Der Endpunkt für die Token-Erstellung validiert keine Scope-Namen, sodass Tippfehler oder ungültige Scope-Strings erst erkannt werden, wenn Sie versuchen, das Token zu verwenden."
},
{
"question": "Beeinflussen Scopes die Ratenbegrenzungen?",
"answer": "Nein. Ratenbegrenzungen basieren auf Ihrem Zendesk-Plan und gelten unabhängig davon, welche Scopes Ihr Token hat. Allerdings können permissivere Scopes es einfacher machen, versehentlich Ratenbegrenzungen zu erreichen, wenn Ihre Anwendung viele Schreibanfragen stellt."
}
],
"supportLink": null
}
}
---
Wenn Sie Integrationen mit Zendesk erstellen, ist es entscheidend zu kontrollieren, was Ihre Anwendung tun kann und was nicht. OAuth Scopes fungieren als Berechtigungstore und ermöglichen es Ihnen, genau festzulegen, auf welche Teile der Zendesk API Ihre Anwendung zugreifen kann.
Im Gegensatz zu API-Token, die einen breiten Zugriff auf Ihr gesamtes Zendesk-Konto gewähren, ermöglichen Ihnen OAuth Scopes, dem Prinzip der geringsten Privilegien zu folgen. Sie fordern nur die Berechtigungen an, die Sie benötigen, nicht mehr. Dies macht Ihre Integrationen sicherer und einfacher zu überprüfen.
In diesem Leitfaden führen wir Sie durch alles, was Sie über Zendesk API OAuth Scopes wissen müssen: was sie sind, welche verfügbar sind, wie Sie sie implementieren und bewährte Verfahren, um Ihre Integrationen sicher zu halten.

## Was sind Zendesk API OAuth Scopes?
OAuth Scopes in Zendesk sind Berechtigungserklärungen, die den Zugriff auf API-Ressourcen steuern. Wenn Sie ein OAuth-Token erstellen, geben Sie Scopes an, die bestimmen, welche Aktionen Ihre Anwendung ausführen kann: Tickets lesen, in Benutzerdatensätze schreiben, Help Center-Inhalte verwalten usw.
Stellen Sie sich Scopes als Schlüssel zu bestimmten Räumen in einem Gebäude vor. Anstatt einen Hauptschlüssel zu haben, der jede Tür öffnet (wie ein API-Token), fordern Sie Schlüssel nur für die Räume an, die Sie betreten müssen. Wenn Ihre Integration nur Ticketdaten lesen muss, fordern Sie den Scope `read` oder `tickets:read` an. Sie erhalten keinen Zugriff, um Benutzer zu löschen oder Trigger zu ändern.
Dieser granulare Ansatz ist aus mehreren Gründen wichtig:
- **Sicherheit**: Wenn ein Token kompromittiert wird, ist der Schaden auf die Scoped-Berechtigungen beschränkt
- **Compliance**: Sie können genau nachweisen, auf welche Daten Ihre Anwendung zugreift
- **Benutzervertrauen**: Endbenutzer sehen genau, welche Berechtigungen sie während der OAuth-Autorisierung erteilen
- **Debugging**: Wenn etwas kaputt geht, wissen Sie genau, welche Berechtigungen betroffen sind
Zendesk unterstützt zwei Haupt-Scope-Formate, je nachdem, wie Sie Ihre Token erstellen. Die [OAuth Tokens API](https://developer.zendesk.com/api-reference/ticketing/oauth/oauth_tokens/) verwendet ein Array-Format (`"scopes": ["read"]`), während der [Grant-Type-Token-Endpunkt](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/) eine leerzeichengetrennte Zeichenkette verwendet (`"scope": "read write"`). Wir werden beide Ansätze im Implementierungsabschnitt behandeln. Für einen tieferen Vergleich von OAuth versus API-Token siehe [Zendesks Authentifizierungsleitfaden](https://developer.zendesk.com/documentation/api-basics/authentication/oauth-vs-api-tokens/).
## Verfügbare OAuth Scopes in Zendesk
Zendesk organisiert Scopes in zwei Kategorien: breite Scopes, die für alle Ressourcen gelten, und ressourcenspezifische Scopes, die auf einzelne API-Endpunkte abzielen.
### Breite Scopes
Diese drei Scopes steuern den Zugriff auf alle Zendesk-Ressourcen:
| Scope | Zugriffsebene | Am besten geeignet für |
|-------|--------------|----------|
| `read` | GET-Endpunkte und Sideloading | Reporting-Tools, Analyse-Dashboards, schreibgeschützte Integrationen |
| `write` | POST-, PUT-, DELETE-Endpunkte | Synchronisierungstools, Automatisierungsplattformen, Zwei-Wege-Integrationen |
| `impersonate` | Anfragen im Namen von Endbenutzern | Kundenportale, eingebettete Support-Widgets, Proxy-Anwendungen |
Der Scope `impersonate` verdient besondere Erwähnung. Er ermöglicht es Administratoren, API-Anfragen im Namen von Endbenutzern zu stellen, was nützlich ist, wenn kundenorientierte Anwendungen erstellt werden, die Tickets erstellen oder auf den Anfrageverlauf zugreifen müssen, ohne Administratoranmeldeinformationen preiszugeben. Dieser Scope erfordert Administratorrechte und sollte sorgfältig verwendet werden.
### Ressourcenspezifische Scopes
Für eine granulare Steuerung ermöglicht Zendesk die Beschränkung von Berechtigungen auf bestimmte Ressourcen mithilfe der Syntax `resource:scope`. Hier sind die Ressourcen, die Scoped-Zugriff unterstützen:
| Ressource | Lese-Scope | Schreib-Scope | Hinweise |
|----------|------------|-------------|-------|
| tickets | `tickets:read` | `tickets:write` | Kernfunktionen für das Ticketing |
| users | `users:read` | `users:write` | Benutzerverwaltung und Profile |
| organizations | `organizations:read` | `organizations:write` | Organisationsdatensätze |
| auditlogs | `auditlogs:read` | N/A | Von Natur aus schreibgeschützt |
| hc (Help Center) | `hc:read` | `hc:write` | Artikel, Kategorien, Abschnitte |
| apps | `apps:read` | `apps:write` | Verwaltung des App-Marktplatzes |
| triggers | `triggers:read` | `triggers:write` | Automatisierung von Geschäftsregeln |
| automations | `automations:read` | `automations:write` | Zeitbasierte Automatisierungen |
| targets | `targets:read` | `targets:write` | Benachrichtigungsziele |
| webhooks | `webhooks:read` | `webhooks:write` | Webhook-Konfiguration |
| macros | `macros:read` | `macros:write` | Vorgefertigte Antworten |
| requests | `requests:read` | `requests:write` | Ticket-Schnittstelle für Endbenutzer |
| satisfaction_ratings | `satisfaction_ratings:read` | `satisfaction_ratings:write` | CSAT-Daten |
| dynamic_content | `dynamic_content:read` | `dynamic_content:write` | Dynamische Inhaltselemente |
| any_channel | N/A | `any_channel:write` | Nur Schreiben |
| web_widget | N/A | `web_widget:write` | Nur Schreiben |
| zis | `zis:read` | `zis:write` | Zendesk Integration Services |
Die Flexibilität hier ist enorm. Sie können Scopes kombinieren, um präzise Berechtigungssätze zu erstellen. Zum Beispiel gibt Ihnen `"scopes": ["tickets:read", "users:write", "organizations:read"]` Lesezugriff auf Tickets und Organisationen sowie die Möglichkeit, Benutzerdatensätze zu aktualisieren.
## OAuth Scope Syntax und Format
Die richtige Syntax ist wichtig, da Zendesk auch bei ungültigen Scope-Formaten Token zurückgibt, aber API-Aufrufe mit diesen Token mit "Forbidden"-Fehlern fehlschlagen.
### Nicht-Grant-Type-Token (Scopes-Array)
Wenn Sie die [OAuth Tokens API](https://developer.zendesk.com/api-reference/ticketing/oauth/oauth_tokens/#create-token) verwenden, um Token direkt zu erstellen (normalerweise für den internen Gebrauch oder von Administratoren erstellte Token), verwenden Sie das Array-Format:
```json
{
"token": {
"client_id": 1234,
"scopes": ["tickets:read", "users:read"]
}
}
Wichtige Punkte:
- Der Parametername ist
scopes(Plural) - Der Wert ist ein JSON-Array von Zeichenketten
- Jeder Scope ist ein separates Array-Element
- Endpunkt:
POST /api/v2/oauth/tokens
Grant-Type-Token (Scope-Zeichenkette)
Wenn Sie den OAuth-Autorisierungsablauf implementieren (Autorisierungscode, Refresh-Token oder Client-Anmeldeinformationen), verwenden Sie das leerzeichengetrennte Zeichenkettenformat:
{
"grant_type": "authorization_code",
"code": "7xqwtlf3rrdj8uyeb1yf",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"scope": "tickets:read users:write"
}
Wichtige Punkte:
- Der Parametername ist
scope(Singular) - Der Wert ist eine leerzeichengetrennte Zeichenkette
- Mehrere Scopes gehören in dieselbe Zeichenkette
- Endpunkt:
POST /oauth/tokens
Häufige Scope-Kombinationen
Hier sind praktische Scope-Kombinationen für typische Anwendungsfälle:
Schreibgeschütztes Reporting:
"scopes": ["read"]
Ticketverwaltung mit Benutzersuche:
"scopes": ["tickets:read", "tickets:write", "users:read"]
Verwaltung von Help Center-Inhalten:
"scopes": ["hc:read", "hc:write", "tickets:read"]
Voller Administratorzugriff (sparsam verwenden):
"scopes": ["read", "write"]
So implementieren Sie OAuth Scopes in Ihrer Anwendung
Lassen Sie uns die vollständige Implementierung durchgehen, von der Erstellung eines OAuth-Clients bis zur Durchführung Ihrer ersten Scoped-API-Anfrage.
Schritt 1: Erstellen Sie einen OAuth-Client in Zendesk
Bevor Sie Scoped-Token anfordern können, müssen Sie Ihre Anwendung als OAuth-Client in Zendesk registrieren.
-
Melden Sie sich als Administrator in Ihrem Zendesk-Konto an
-
Navigieren Sie zu Admin Center > Apps und Integrationen > APIs > OAuth-Clients
-
Klicken Sie auf OAuth-Client hinzufügen
-
Füllen Sie die erforderlichen Felder aus:
- Name: Ihr Anwendungsname (Benutzer sehen dies während der Autorisierung)
- Beschreibung: Kurze Beschreibung dessen, was Ihre App tut
- Client-Art: Wählen Sie Öffentlich für mobile/SPA-Apps, Vertraulich für serverseitige Apps
- Redirect-URLs: Ihre Callback-URLs (müssen HTTPS sein, außer für localhost)
-
Klicken Sie auf Speichern
-
Kopieren Sie sofort den Secret-Wert (er wird nur einmal vollständig angezeigt)
-
Notieren Sie sich Ihre Eindeutige Kennung (dies ist Ihre
client_id)
Wichtig: Wenn Sie Öffentlich als Client-Art auswählen, müssen Sie PKCE (Proof Key for Code Exchange) aus Sicherheitsgründen implementieren. Vertrauliche Clients können PKCE, Client Secret oder beides verwenden.
Schritt 2: Fordern Sie die Autorisierung mit Scopes an
Senden Sie Ihre Benutzer mit Ihren angeforderten Scopes an den Autorisierungs-Endpunkt von Zendesk:
https://{subdomain}.zendesk.com/oauth/authorizations/new?
response_type=code&
redirect_uri=https://your-app.com/callback&
client_id=your_unique_identifier&
scope=read%20write&
state=random_state_string

Erforderliche Parameter:
response_type=code: Gibt an, dass Sie einen Autorisierungscode wünschenredirect_uri: Muss mit einer der in Schritt 1 registrierten URLs übereinstimmenclient_id: Die eindeutige Kennung Ihres OAuth-Clientsscope: Leerzeichengetrennte Liste der angeforderten Scopes
Empfohlene Parameter:
state: Zufällige Zeichenkette, um CSRF-Angriffe zu verhindern (überprüfen Sie, ob dies übereinstimmt, wenn der Benutzer zurückkehrt)code_challengeundcode_challenge_method=S256: Erforderlich für PKCE mit öffentlichen Clients
Der Benutzer sieht einen Autorisierungsbildschirm, der die Scopes auflistet, die Sie anfordern. Er wird den Zugriff genehmigen oder verweigern.
Schritt 3: Tauschen Sie den Autorisierungscode gegen ein Zugriffstoken aus
Wenn der Benutzer zustimmt, leitet Zendesk mit einem Autorisierungscode an Ihre Callback-URL weiter:
https://your-app.com/callback?code=7xqwtlf3rrdj8uyeb1yf&state=random_state_string
Tauschen Sie diesen Code gegen ein Zugriffstoken aus:
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://your-app.com/callback",
"scope": "read write"
}'
Wichtig: Der Autorisierungscode läuft in 120 Sekunden ab. Tauschen Sie ihn umgehend aus.
Die Antwort enthält Ihr Zugriffstoken und Ihr Refresh-Token:
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"refresh_token": "31048ba4d7c601302f3173f243da835f",
"token_type": "bearer",
"scope": "read write",
"expires_in": 172800,
"refresh_token_expires_in": 800000
}
Schritt 4: Verwenden Sie das Zugriffstoken in API-Anfragen
Fügen Sie das Token als Bearer-Token in Ihre API-Anfragen ein:
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
Das Token funktioniert nur für Endpunkte, die Ihren Scopes entsprechen. Ein Token mit dem Scope tickets:read kann Tickets abrufen, aber keine erstellen (dafür wäre tickets:write erforderlich).
Häufige Scope-Konfigurationen für typische Anwendungsfälle
Verschiedene Integrationen benötigen unterschiedliche Berechtigungssätze. Hier sind Konfigurationen, die wir häufig sehen:
Reporting- und Analyse-Tools
Diese Tools müssen nur Daten lesen:
"scope": "read"
Oder restriktiver:
"scope": "tickets:read users:read organizations:read"
Zwei-Wege-Synchronisierungs-Integrationen
Synchronisierungs-Tools müssen über mehrere Ressourcen hinweg lesen und schreiben:
"scope": "tickets:read tickets:write users:read users:write organizations:read organizations:write"
Verwaltung von Help Center-Inhalten
Für die Verwaltung von Wissensdatenbankartikeln:
"scope": "hc:read hc:write"
Kundenorientierte Portale
Wenn Ihre Anwendung im Namen von Endbenutzern agiert:
"scope": "requests:read requests:write impersonate"
Automatisierungs- und Workflow-Tools
Für Tools, die Geschäftsregeln verwalten:
"scope": "triggers:read triggers:write automations:read automations:write webhooks:read webhooks:write"
Fehlerbehebung bei Scope-bezogenen Fehlern
Auch bei korrekter Implementierung treten Fehler auf. So beheben Sie die häufigsten Fehler:
"Forbidden"-Fehler (403)
Dies ist der häufigste Scope-bezogene Fehler. Er bedeutet, dass Ihrem Token die Berechtigung für den angeforderten Endpunkt fehlt.
Ursachen:
- Fehlender erforderlicher Scope für den Endpunkt
- Ungültiges Scope-Format (Array vs. String-Fehlpaarung)
- Die Rolle des Benutzers hat keine Berechtigung (OAuth Scopes werden durch Benutzerberechtigungen eingeschränkt)
Lösung: Überprüfen Sie in der Zendesk API-Dokumentation, welcher Scope der Endpunkt benötigt, und überprüfen Sie dann, ob Ihr Token ihn enthält. Denken Sie daran, dass einige Endpunkte unabhängig von OAuth Scopes Administratorrechte erfordern. Weitere Informationen zum Erstellen und Verwalten von Token finden Sie im Zendesk OAuth-Token-Tutorial.
401 Nicht autorisiert
Dies deutet auf ein abgelaufenes oder widerrufenes Token hin:
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}
Lösung: Verwenden Sie Ihr Refresh-Token, um ein neues Zugriffstoken zu erhalten, oder leiten Sie den Benutzer erneut durch den Autorisierungsablauf, wenn das Refresh-Token ebenfalls abgelaufen ist.
Ungültiges Scope-Format
Wenn Sie Scopes im falschen Format übergeben (Array, wenn eine Zeichenkette erwartet wird, oder umgekehrt), kann Zendesk dennoch ein Token ausstellen, aber API-Aufrufe schlagen fehl.
Lösung: Überprüfen Sie nochmals, welchen Endpunkt Sie verwenden:
/api/v2/oauth/tokensverwendet dasscopes": []Array-Format/oauth/tokensverwendet dasscope": ""String-Format
Scope vs. Rollen-Fehlpaarung
OAuth Scopes werden durch die Rolle des Benutzers gefiltert. Das OAuth-Token eines Agenten kann nicht auf reine Administrator-Endpunkte zugreifen, selbst wenn das Token den Scope write hat.
Lösung: Stellen Sie sicher, dass der Benutzer, der Ihre Anwendung autorisiert, die erforderlichen Rollenberechtigungen für die Anforderungen Ihrer Integration hat.
Bewährte Verfahren für die Sicherheit von OAuth Scopes
Wenn Sie diese Praktiken befolgen, bleiben Ihre Zendesk-Integrationen sicher:
Fordern Sie minimale Scopes an
Fordern Sie nur die Berechtigungen an, die Sie unbedingt benötigen. Wenn Ihre Integration nur Tickets liest, fordern Sie nicht den Scope write an. Dies begrenzt die Gefährdung, wenn ein Token kompromittiert wird.
Verwenden Sie nach Möglichkeit vertrauliche Clients
Serverseitige Anwendungen sollten vertrauliche Clients mit Client Secrets verwenden. Öffentliche Clients (mobile Apps, SPAs) müssen PKCE implementieren.
Implementieren Sie eine Token-Aktualisierungslogik
Zugriffstoken laufen ab. Sie sollten eine automatische Aktualisierungslogik in Ihre Anwendung einbauen:
response = requests.get(api_url, headers=headers)
if response.status_code == 401:
new_token = refresh_access_token(refresh_token)
headers['Authorization'] = f'Bearer {new_token}'
response = requests.get(api_url, headers=headers)
Speichern Sie Token sicher
Behandeln Sie Zugriffstoken und Refresh-Token wie Passwörter. Speichern Sie sie verschlüsselt, protokollieren Sie sie niemals und legen Sie sie nicht in clientseitigem Code offen.
Validieren Sie State-Parameter
Fügen Sie immer den Parameter state in Ihrem OAuth-Ablauf ein und validieren Sie ihn, um CSRF-Angriffe zu verhindern.
Erwägen Sie die Verwendung einer sicheren Integrationsplattform
Das sichere Erstellen von OAuth-Integrationen erfordert sorgfältige Beachtung der Token-Speicherung, der Aktualisierungslogik und der Fehlerbehandlung. Wenn Sie Kundensupport-Integrationen erstellen, sollten Sie die Verwendung einer Plattform wie eesel AI in Betracht ziehen, die Zendesk OAuth sicher mit integrierter Scope-Verwaltung handhabt. Unser AI Agent integriert sich mit Zendesk unter Verwendung minimal erforderlicher Scopes und folgt standardmäßig dem Prinzip der geringsten Privilegien. Sie können auch mehr über das Anzeigen und Verwalten Ihrer OAuth-Token in der Zendesk-Dokumentation erfahren.

Fazit
Zendesk API OAuth Scopes geben Ihnen die präzise Kontrolle darüber, worauf Ihre Integrationen zugreifen können. Indem Sie die verfügbaren Scopes verstehen, sie korrekt implementieren und bewährte Sicherheitsverfahren befolgen, können Sie Integrationen erstellen, die sowohl leistungsstark als auch sicher sind.
Die wichtigsten Erkenntnisse:
- Verwenden Sie breite Scopes (
read,write) für einfache Integrationen, ressourcenspezifische Scopes für granulare Kontrolle - Passen Sie Ihr Scope-Format an Ihren Token-Endpunkt an (Array vs. String)
- Fordern Sie immer minimale Berechtigungen an
- Behandeln Sie den Token-Ablauf mit Aktualisierungslogik auf elegante Weise
- Denken Sie daran, dass Benutzerrollen OAuth Scopes einschränken
Egal, ob Sie ein einfaches Reporting-Tool oder eine komplexe Zwei-Wege-Synchronisierung erstellen, die richtige Scope-Konfiguration ist die Grundlage einer sicheren Zendesk-Integration.
Diesen Beitrag teilen

Article by


