{
"title": "Portées OAuth de l’API Zendesk : Un guide complet pour les développeurs",
"slug": "zendesk-api-oauth-scopes",
"locale": "fr",
"date": "2026-02-27",
"updated": "2026-02-27",
"template": "default",
"excerpt": "Un guide pratique pour comprendre et mettre en œuvre les portées OAuth de l’API Zendesk pour une authentification API sécurisée.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"OAuth",
"API",
"Authentication",
"Developer"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Portées OAuth de l’API Zendesk : Un guide complet pour les développeurs",
"description": "Un guide pratique pour comprendre et mettre en œuvre les portées OAuth de l’API Zendesk pour une authentification API sécurisée.",
"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": "Image de bannière pour Portées OAuth de l’API Zendesk : Un guide complet pour les développeurs",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Foire aux questions",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Puis-je modifier les portées d’un jeton existant ?",
"answer": "Non. Vous ne pouvez pas modifier les portées d’un jeton existant. Pour modifier les autorisations, vous devez générer un nouveau jeton avec les portées mises à jour en renvoyant l’utilisateur dans le flux d’autorisation."
},
{
"question": "Quelle est la différence entre les portées OAuth et les rôles d’utilisateur dans Zendesk ?",
"answer": "Les portées OAuth contrôlent les points de terminaison API auxquels un jeton peut accéder. Les rôles d’utilisateur (administrateur, agent, utilisateur final) contrôlent les actions qu’un utilisateur peut effectuer dans Zendesk. Les autorisations effectives d’un jeton sont l’intersection de ses portées et du rôle de l’utilisateur autorisateur. Un agent ne peut pas effectuer d’actions d’administrateur, même avec de larges portées OAuth."
},
{
"question": "Comment savoir quelles portées un point de terminaison requiert ?",
"answer": "Consultez la documentation de l’API Zendesk. La plupart des descriptions de points de terminaison incluent la portée requise. Généralement, les points de terminaison GET nécessitent « read » ou « resource:read », tandis que les points de terminaison POST/PUT/DELETE nécessitent « write » ou « resource:write »."
},
{
"question": "Puis-je utiliser les portées OAuth avec les jetons API ?",
"answer": "Non. Les jetons API sont un mécanisme d’authentification différent qui accorde un large accès au compte sans restrictions de portée. Les jetons OAuth utilisent des portées. Choisissez OAuth pour des autorisations granulaires, les jetons API pour des scripts simples où le contrôle de la portée n’est pas nécessaire."
},
{
"question": "Que se passe-t-il si je demande une portée qui n’existe pas ?",
"answer": "Zendesk émettra un jeton, mais les appels API renverront des erreurs « Forbidden ». Le point de terminaison de création de jeton ne valide pas les noms de portée, donc les fautes de frappe ou les chaînes de portée non valides ne seront pas détectées tant que vous n’aurez pas essayé d’utiliser le jeton."
},
{
"question": "Les portées affectent-elles les limites de débit ?",
"answer": "Non. Les limites de débit sont basées sur votre plan Zendesk et s’appliquent indépendamment des portées de votre jeton. Cependant, des portées plus permissives pourraient rendre plus facile d’atteindre accidentellement les limites de débit si votre application effectue de nombreuses requêtes d’écriture."
}
],
"supportLink": null
}
}
---
Lorsque vous créez des intégrations avec Zendesk, il est essentiel de contrôler ce que votre application peut et ne peut pas faire. Les portées OAuth agissent comme des portes d’autorisation, vous permettant de spécifier exactement les parties de l’API Zendesk auxquelles votre application peut accéder.
Contrairement aux jetons API, qui accordent un large accès à l’ensemble de votre compte Zendesk, les portées OAuth vous permettent de suivre le principe du moindre privilège. Vous ne demandez que les autorisations dont vous avez besoin, rien de plus. Cela rend vos intégrations plus sécurisées et plus faciles à auditer.
Dans ce guide, nous allons passer en revue tout ce que vous devez savoir sur les portées OAuth de l’API Zendesk : ce qu’elles sont, lesquelles sont disponibles, comment les mettre en œuvre et les meilleures pratiques pour assurer la sécurité de vos intégrations.
## Que sont les portées OAuth de l’API Zendesk ?
Les portées OAuth dans Zendesk sont des déclarations d’autorisation qui contrôlent l’accès aux ressources API. Lorsque vous créez un jeton OAuth, vous spécifiez des portées qui déterminent les actions que votre application peut effectuer : lire des tickets, écrire dans des enregistrements d’utilisateurs, gérer le contenu du centre d’aide, et ainsi de suite.
Considérez les portées comme des clés pour des pièces spécifiques dans un bâtiment. Au lieu d’avoir une clé principale qui ouvre toutes les portes (comme un jeton API), vous ne demandez des clés que pour les pièces dans lesquelles vous devez entrer. Si votre intégration n’a besoin que de lire les données des tickets, vous demandez la portée `read` ou `tickets:read`. Vous n’aurez pas accès à la suppression d’utilisateurs ou à la modification de déclencheurs.
Cette approche granulaire est importante pour plusieurs raisons :
- **Sécurité** : Si un jeton est compromis, les dommages sont limités aux autorisations définies par la portée
- **Conformité** : Vous pouvez démontrer exactement les données auxquelles votre application accède
- **Confiance de l’utilisateur** : Les utilisateurs finaux voient exactement les autorisations qu’ils accordent lors de l’autorisation OAuth
- **Débogage** : Lorsque quelque chose se casse, vous savez exactement quelles autorisations sont impliquées
Zendesk prend en charge deux principaux formats de portée selon la façon dont vous créez vos jetons. L’[API des jetons OAuth](https://developer.zendesk.com/api-reference/ticketing/oauth/oauth_tokens/) utilise un format de tableau (`"scopes": ["read"]`), tandis que le [point de terminaison de jeton de type d’autorisation](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/) utilise une chaîne séparée par des espaces (`"scope": "read write"`). Nous aborderons les deux approches dans la section sur la mise en œuvre. Pour une comparaison plus approfondie entre OAuth et les jetons API, consultez le [guide d’authentification de Zendesk](https://developer.zendesk.com/documentation/api-basics/authentication/oauth-vs-api-tokens/).
## Portées OAuth disponibles dans Zendesk
Zendesk organise les portées en deux catégories : les portées larges qui s’appliquent à toutes les ressources et les portées spécifiques aux ressources qui ciblent des points de terminaison API individuels.
### Portées larges
Ces trois portées contrôlent l’accès à toutes les ressources Zendesk :
| Portée | Niveau d’accès | Idéal pour |
|-------|--------------|----------|
| `read` | Points de terminaison GET et chargement latéral | Outils de reporting, tableaux de bord d’analyse, intégrations en lecture seule |
| `write` | Points de terminaison POST, PUT, DELETE | Outils de synchronisation, plateformes d’automatisation, intégrations bidirectionnelles |
| `impersonate` | Requêtes au nom des utilisateurs finaux | Portails clients, widgets de support intégrés, applications proxy |
La portée `impersonate` mérite une mention spéciale. Elle permet aux administrateurs d’effectuer des requêtes API au nom des utilisateurs finaux, ce qui est utile lors de la création d’applications destinées aux clients qui doivent créer des tickets ou accéder à l’historique des requêtes sans exposer les informations d’identification de l’administrateur. Cette portée nécessite des privilèges d’administrateur et doit être utilisée avec précaution.
### Portées spécifiques aux ressources
Pour un contrôle plus granulaire, Zendesk vous permet de définir des autorisations pour des ressources spécifiques à l’aide de la syntaxe `resource:scope`. Voici les ressources qui prennent en charge l’accès délimité :
| Ressource | Portée de lecture | Portée d’écriture | Notes |
|----------|------------|-------------|-------|
| tickets | `tickets:read` | `tickets:write` | Fonctionnalité de billetterie de base |
| users | `users:read` | `users:write` | Gestion des utilisateurs et profils |
| organizations | `organizations:read` | `organizations:write` | Enregistrements d’organisation |
| auditlogs | `auditlogs:read` | N/A | Lecture seule par conception |
| hc (centre d’aide) | `hc:read` | `hc:write` | Articles, catégories, sections |
| apps | `apps:read` | `apps:write` | Gestion de la place de marché des applications |
| triggers | `triggers:read` | `triggers:write` | Automatisation des règles métier |
| automations | `automations:read` | `automations:write` | Automatisations basées sur le temps |
| targets | `targets:read` | `targets:write` | Cibles de notification |
| webhooks | `webhooks:read` | `webhooks:write` | Configuration des webhooks |
| macros | `macros:read` | `macros:write` | Réponses prédéfinies |
| requests | `requests:read` | `requests:write` | Interface de ticket utilisateur final |
| satisfaction_ratings | `satisfaction_ratings:read` | `satisfaction_ratings:write` | Données CSAT |
| dynamic_content | `dynamic_content:read` | `dynamic_content:write` | Éléments de contenu dynamique |
| any_channel | N/A | `any_channel:write` | Écriture seule |
| web_widget | N/A | `web_widget:write` | Écriture seule |
| zis | `zis:read` | `zis:write` | Services d’intégration Zendesk |
La flexibilité ici est puissante. Vous pouvez mélanger et assortir les portées pour créer des ensembles d’autorisations précis. Par exemple, `"scopes": ["tickets:read", "users:write", "organizations:read"]` vous donne un accès en lecture aux tickets et aux organisations, ainsi que la possibilité de mettre à jour les enregistrements d’utilisateurs.
## Syntaxe et format des portées OAuth
Il est important de bien comprendre la syntaxe, car Zendesk renvoie des jetons même avec des formats de portée non valides, mais les appels API avec ces jetons échoueront avec des erreurs « Forbidden ».
### Jetons non de type autorisation (tableau de portées)
Lorsque vous utilisez l’[API des jetons OAuth](https://developer.zendesk.com/api-reference/ticketing/oauth/oauth_tokens/#create-token) pour créer directement des jetons (généralement pour une utilisation interne ou des jetons créés par l’administrateur), utilisez le format de tableau :
```json
{
"token": {
"client_id": 1234,
"scopes": ["tickets:read", "users:read"]
}
}
Points clés :
- Le nom du paramètre est
scopes(pluriel) - La valeur est un tableau JSON de chaînes
- Chaque portée est un élément de tableau distinct
- Point de terminaison :
POST /api/v2/oauth/tokens
Jetons de type autorisation (chaîne de portée)
Lors de la mise en œuvre du flux d’autorisation OAuth (code d’autorisation, jeton d’actualisation ou informations d’identification du client), utilisez le format de chaîne séparée par des espaces :
{
"grant_type": "authorization_code",
"code": "7xqwtlf3rrdj8uyeb1yf",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"scope": "tickets:read users:write"
}
Points clés :
- Le nom du paramètre est
scope(singulier) - La valeur est une chaîne séparée par des espaces
- Plusieurs portées vont dans la même chaîne
- Point de terminaison :
POST /oauth/tokens
Combinaisons de portées courantes
Voici des combinaisons de portées pratiques pour les cas d’utilisation courants :
Reporting en lecture seule :
"scopes": ["read"]
Gestion des tickets avec recherche d’utilisateurs :
"scopes": ["tickets:read", "tickets:write", "users:read"]
Gestion du contenu du centre d’aide :
"scopes": ["hc:read", "hc:write", "tickets:read"]
Accès administrateur complet (à utiliser avec parcimonie) :
"scopes": ["read", "write"]
Comment mettre en œuvre les portées OAuth dans votre application
Passons en revue la mise en œuvre complète, de la création d’un client OAuth à la réalisation de votre première requête API délimitée.
Étape 1 : Créer un client OAuth dans Zendesk
Avant de pouvoir demander des jetons délimités, vous devez enregistrer votre application en tant que client OAuth dans Zendesk.
-
Connectez-vous à votre compte Zendesk en tant qu’administrateur
-
Accédez à Centre d’administration > Applications et intégrations > API > Clients OAuth
-
Cliquez sur Ajouter un client OAuth
-
Remplissez les champs obligatoires :
- Nom : Le nom de votre application (les utilisateurs le verront lors de l’autorisation)
- Description : Brève description de ce que fait votre application
- Type de client : Choisissez Public pour les applications mobiles/SPA, Confidentiel pour les applications côté serveur
- URL de redirection : Vos URL de rappel (doivent être HTTPS, sauf pour localhost)
-
Cliquez sur Enregistrer
-
Copiez immédiatement la valeur Secret (elle n’est affichée qu’une seule fois entièrement)
-
Notez votre Identifiant unique (c’est votre
client_id)
Important : Si vous sélectionnez Public comme type de client, vous devez mettre en œuvre PKCE (Proof Key for Code Exchange) pour la sécurité. Les clients confidentiels peuvent utiliser PKCE, le secret client ou les deux.
Étape 2 : Demander une autorisation avec des portées
Envoyez vos utilisateurs au point de terminaison d’autorisation de Zendesk avec les portées demandées :
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
Paramètres obligatoires :
response_type=code: Indique que vous voulez un code d’autorisationredirect_uri: Doit correspondre à l’une des URL enregistrées à l’étape 1client_id: L’identifiant unique de votre client OAuthscope: Liste des portées demandées séparées par des espaces
Paramètres recommandés :
state: Chaîne aléatoire pour empêcher les attaques CSRF (vérifiez que cela correspond lorsque l’utilisateur revient)code_challengeetcode_challenge_method=S256: Requis pour PKCE avec les clients publics
L’utilisateur verra un écran d’autorisation énumérant les portées que vous demandez. Il approuvera ou refusera l’accès.
Étape 3 : Échanger le code d’autorisation contre un jeton d’accès
Lorsque l’utilisateur approuve, Zendesk redirige vers votre URL de rappel avec un code d’autorisation :
https://your-app.com/callback?code=7xqwtlf3rrdj8uyeb1yf&state=random_state_string
Échangez ce code contre un jeton d’accès :
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"
}'
Important : Le code d’autorisation expire dans 120 secondes. Échangez-le rapidement.
La réponse inclut votre jeton d’accès et votre jeton d’actualisation :
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"refresh_token": "31048ba4d7c601302f3173f243da835f",
"token_type": "bearer",
"scope": "read write",
"expires_in": 172800,
"refresh_token_expires_in": 800000
}
Étape 4 : Utiliser le jeton d’accès dans les requêtes API
Incluez le jeton dans vos requêtes API en tant que jeton Bearer :
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
Le jeton ne fonctionne que pour les points de terminaison correspondant à vos portées. Un jeton avec la portée tickets:read peut récupérer des tickets, mais ne peut pas les créer (cela nécessiterait tickets:write).
Configurations de portées courantes pour les cas d’utilisation courants
Différentes intégrations nécessitent différents ensembles d’autorisations. Voici les configurations que nous voyons fréquemment :
Outils de reporting et d’analyse
Ces outils n’ont besoin que de lire des données :
"scope": "read"
Ou plus restrictif :
"scope": "tickets:read users:read organizations:read"
Intégrations de synchronisation bidirectionnelles
Les outils de synchronisation doivent lire et écrire sur plusieurs ressources :
"scope": "tickets:read tickets:write users:read users:write organizations:read organizations:write"
Gestion du contenu du centre d’aide
Pour la gestion des articles de la base de connaissances :
"scope": "hc:read hc:write"
Portails destinés aux clients
Lorsque votre application agit au nom des utilisateurs finaux :
"scope": "requests:read requests:write impersonate"
Outils d’automatisation et de flux de travail
Pour les outils qui gèrent les règles métier :
"scope": "triggers:read triggers:write automations:read automations:write webhooks:read webhooks:write"
Dépannage des erreurs liées à la portée
Même avec une mise en œuvre appropriée, vous rencontrerez des erreurs. Voici comment gérer les plus courantes :
Erreurs « Forbidden » (403)
Il s’agit de l’erreur liée à la portée la plus courante. Cela signifie que votre jeton n’a pas l’autorisation pour le point de terminaison demandé.
Causes :
- Portée requise manquante pour le point de terminaison
- Format de portée non valide (incompatibilité entre tableau et chaîne)
- Le rôle de l’utilisateur n’a pas l’autorisation (les portées OAuth sont limitées par les autorisations de l’utilisateur)
Solution : Vérifiez quelle portée le point de terminaison requiert dans la documentation de l’API Zendesk, puis vérifiez que votre jeton l’inclut. N’oubliez pas que certains points de terminaison nécessitent des privilèges d’administrateur, quelles que soient les portées OAuth. Pour plus de détails sur la création et la gestion des jetons, consultez le didacticiel sur les jetons OAuth de Zendesk.
401 Non autorisé
Cela indique un jeton expiré ou révoqué :
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}
Solution : Utilisez votre jeton d’actualisation pour obtenir un nouveau jeton d’accès, ou redirigez à nouveau l’utilisateur dans le flux d’autorisation si le jeton d’actualisation a également expiré.
Format de portée non valide
Si vous transmettez des portées dans le mauvais format (tableau lorsque la chaîne est attendue, ou vice versa), Zendesk peut toujours émettre un jeton, mais les appels API échoueront.
Solution : Vérifiez quel point de terminaison vous utilisez :
/api/v2/oauth/tokensutilise le format de tableau"scopes": []/oauth/tokensutilise le format de chaîne"scope": ""
Incompatibilité entre la portée et le rôle
Les portées OAuth sont filtrées par le rôle de l’utilisateur. Le jeton OAuth d’un agent ne peut pas accéder aux points de terminaison réservés aux administrateurs, même si le jeton a la portée write.
Solution : Assurez-vous que l’utilisateur qui autorise votre application dispose des autorisations de rôle nécessaires pour les exigences de votre intégration.
Meilleures pratiques pour la sécurité des portées OAuth
Le respect de ces pratiques assurera la sécurité de vos intégrations Zendesk :
Demander des portées minimales
Ne demandez que les autorisations dont vous avez absolument besoin. Si votre intégration ne fait que lire des tickets, ne demandez pas la portée write. Cela limite l’exposition si un jeton est compromis.
Utiliser des clients confidentiels lorsque cela est possible
Les applications côté serveur doivent utiliser des clients confidentiels avec des secrets clients. Les clients publics (applications mobiles, SPA) doivent mettre en œuvre PKCE.
Mettre en œuvre la logique d’actualisation des jetons
Les jetons d’accès expirent. Vous devrez intégrer une logique d’actualisation automatique dans votre application :
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)
Stocker les jetons en toute sécurité
Traitez les jetons d’accès et les jetons d’actualisation comme des mots de passe. Stockez-les chiffrés, ne les enregistrez jamais et ne les exposez pas dans le code côté client.
Valider les paramètres d’état
Incluez et validez toujours le paramètre state dans votre flux OAuth pour empêcher les attaques CSRF.
Envisager d’utiliser une plateforme d’intégration sécurisée
La création d’intégrations OAuth sécurisées nécessite une attention particulière au stockage des jetons, à la logique d’actualisation et à la gestion des erreurs. Si vous créez des intégrations de support client, envisagez d’utiliser une plateforme comme eesel AI qui gère Zendesk OAuth en toute sécurité avec une gestion appropriée de la portée intégrée. Notre Agent IA s’intègre à Zendesk en utilisant les portées minimales requises, en suivant le principe du moindre privilège par défaut. Vous pouvez également en savoir plus sur l’affichage et la gestion de vos jetons OAuth dans la documentation de Zendesk.
Conclusion
Les portées OAuth de l’API Zendesk vous donnent un contrôle précis sur ce à quoi vos intégrations peuvent accéder. En comprenant les portées disponibles, en les mettant en œuvre correctement et en suivant les meilleures pratiques de sécurité, vous pouvez créer des intégrations à la fois puissantes et sécurisées.
Les principaux points à retenir :
- Utilisez des portées larges (
read,write) pour les intégrations simples, des portées spécifiques aux ressources pour un contrôle granulaire - Faites correspondre votre format de portée à votre point de terminaison de jeton (tableau ou chaîne)
- Demandez toujours des autorisations minimales
- Gérez l’expiration du jeton avec élégance grâce à la logique d’actualisation
- N’oubliez pas que les rôles d’utilisateur limitent les portées OAuth
Que vous créiez un simple outil de reporting ou une synchronisation bidirectionnelle complexe, une configuration de portée appropriée est le fondement d’une intégration Zendesk sécurisée.
Partager cet article
Article by
