Authentification et étendues de l'API Zendesk : un guide complet pour 2026

Si vous créez une intégration avec Zendesk, l'authentification est votre premier obstacle. Si vous vous trompez, vous passerez des heures à déboguer de mystérieuses erreurs 403. Si vous réussissez, vous aurez une connexion sécurisée et maintenable qui fonctionne simplement.

Ce guide couvre tout ce que vous devez savoir sur l'authentification de l'API Zendesk en 2026. Nous allons passer en revue les différentes méthodes d'authentification, expliquer comment fonctionnent les étendues OAuth et vous montrer exactement comment les implémenter avec des exemples de code fonctionnels.

Chez eesel AI, nous créons des intégrations avec Zendesk tous les jours. Nous avons vu ce qui fonctionne, ce qui casse et comment éviter les pièges courants qui font trébucher les développeurs.

Comprendre les méthodes d'authentification de l'API Zendesk

Zendesk offre trois façons d'authentifier les requêtes API, bien qu'une soit en voie de disparition. Décomposons vos options.

Les trois options d'authentification

L'authentification par mot de passe est obsolète et Zendesk recommande de migrer vers des jetons API ou OAuth. Si vous commencez à zéro, ignorez complètement les mots de passe.

Authentification par jeton API

Les jetons API sont l'option la plus simple. Ce sont des mots de passe auto-générés que vous créez dans le Centre d'administration Zendesk.

Voici comment fonctionnent les informations d'identification :

{adresse_email}/token:{jeton_api}

Par exemple :

jdupont@exemple.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Lorsque vous encodez cette chaîne en base64, votre en-tête d'autorisation ressemble à ceci :

Authorization: Basic amR1cG9udEBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

Ou avec curl :

curl https://votredomaine.zendesk.com/api/v2/users.json \
  -u jdupont@exemple.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Principales limitations à connaître :

• Vous pouvez avoir jusqu'à 256 jetons actifs (2048 si vous avez déjà dépassé 256)
• Les jetons peuvent usurper l'identité de n'importe quel utilisateur du compte, y compris les administrateurs
• Pas d'autorisations granulaires : un jeton a le même accès que l'utilisateur qui l'a créé
• Les jetons n'expirent pas, sauf si vous les révoquez manuellement

Source : Documents de sécurité et d'authentification Zendesk

Authentification par jeton d'accès OAuth

OAuth est le meilleur choix pour la plupart des intégrations. Il vous donne un contrôle granulaire sur les autorisations grâce aux étendues, et les jetons sont liés à des utilisateurs spécifiques plutôt que d'avoir un large accès au compte.

Le flux fonctionne comme ceci :

1. Votre application redirige l'utilisateur vers Zendesk pour autoriser l'accès
2. L'utilisateur accorde la permission et Zendesk envoie un code d'autorisation à votre application
3. Votre application échange le code contre un jeton d'accès
4. Vous utilisez le jeton Bearer dans les requêtes API

Voici à quoi ressemble une requête :

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

OAuth prend également en charge les requêtes API côté client à partir des navigateurs, ce que les jetons API ne peuvent pas faire en raison des restrictions CORS.

Source : Documentation d'aide OAuth de Zendesk

Explication des étendues OAuth

Les étendues sont au cœur de la sécurité OAuth. Elles vous permettent de demander uniquement les autorisations dont votre application a réellement besoin, en suivant le principe du moindre privilège.

Que sont les étendues OAuth ?

Considérez les étendues comme des autorisations. Au lieu d'obtenir un accès complet à un compte Zendesk, vous demandez des capacités spécifiques. Un outil de reporting peut n'avoir besoin que d'un accès en lecture aux tickets. Un outil de synchronisation a besoin d'un accès en lecture et en écriture. Un tableau de bord d'administration peut avoir besoin de droits d'usurpation d'identité pour agir au nom des utilisateurs.

Étendues générales

Elles donnent un accès général à toutes les ressources :

• read : Accès aux points de terminaison GET et au chargement latéral des ressources associées
• write : Accès aux points de terminaison POST, PUT et DELETE pour la création, la mise à jour et la suppression
• impersonate : Permet aux administrateurs de faire des requêtes au nom des utilisateurs finaux

Étendues spécifiques aux ressources

Pour un contrôle plus précis, vous pouvez étendre les autorisations à des ressources spécifiques :

Certaines ressources sont en écriture seule : any_channel:write et web_widget:write.

Source : Référence de l'API des jetons OAuth de Zendesk

Différences de format d'étendue (important !)

C'est là que les développeurs se font souvent piéger. Zendesk utilise différents formats selon le point de terminaison que vous utilisez :

Pour l'API des jetons OAuth (/api/v2/oauth/tokens) :

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

Pour le flux d'autorisation (/oauth/tokens) :

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

Le premier utilise un tableau. Le second utilise une chaîne séparée par des espaces. Mélangez-les et vous obtiendrez des erreurs déroutantes.

Implémentation de l'authentification OAuth

Passons en revue l'implémentation complète, étape par étape.

Étape 1 : Créer un client OAuth

Tout d'abord, vous devez enregistrer votre application auprès de Zendesk.

1. Dans le Centre d'administration Zendesk, accédez à Applications et intégrations > API > Clients OAuth

2. Cliquez sur Ajouter un client OAuth

3. Remplissez les détails :

   • Nom : Le nom de votre application (les utilisateurs le voient lors de l'autorisation)
   • Description : Brève explication de ce que fait votre application
   • Type de client : Choisissez Public pour les applications mobiles/SPA ou Confidentiel pour les applications côté serveur
   • URL de redirection : Vos URL de rappel (doivent être HTTPS sauf pour localhost)

4. Cliquez sur Enregistrer

5. Copiez immédiatement la valeur Secret. Elle n'est affichée qu'une seule fois.

6. Notez votre Identifiant unique (c'est votre client_id)

Comprendre les types de clients :

• Les clients confidentiels s'exécutent sur des serveurs sécurisés où les informations d'identification peuvent être protégées. Ils peuvent utiliser PKCE, les secrets clients, ou les deux.
• Les clients publics s'exécutent dans des navigateurs ou des applications mobiles où les informations d'identification sont visibles. Ils doivent utiliser PKCE pour la sécurité.

Si vous créez une intégration côté serveur, choisissez Confidentiel. Pour les applications JavaScript ou les applications mobiles, choisissez Public.

Source : Documentation d'aide OAuth de Zendesk

Étape 2 : Demander l'autorisation

Envoyez vos utilisateurs à la page d'autorisation de Zendesk :

https://{sous-domaine}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  redirect_uri=https://votresite.com/callback&
  client_id=votre_identifiant_unique&
  scope=read%20write&
  state=chaîne_aléatoire

Paramètres requis :

• response_type=code (vous voulez un code d'autorisation en retour)
• redirect_uri (doit correspondre à ce que vous avez enregistré)
• client_id (votre identifiant unique)
• scope (liste des autorisations séparées par des espaces)

Facultatif mais recommandé :

• state (chaîne aléatoire pour empêcher les attaques CSRF)
• code_challenge et code_challenge_method=S256 (pour PKCE)

L'utilisateur voit une page d'autorisation lui demandant s'il souhaite accorder l'accès à votre application. S'il approuve, Zendesk redirige vers votre redirect_uri avec un code d'autorisation :

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

Important : Le code d'autorisation expire dans 120 secondes. Échangez-le rapidement.

Étape 3 : Échanger le code contre un jeton d'accès

Faites une requête POST pour échanger le code :

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

Vous obtiendrez une réponse comme celle-ci :

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

Stockez les deux jetons en toute sécurité. Le jeton d'accès est utilisé pour les appels API. Le jeton de rafraîchissement vous permet d'obtenir un nouveau jeton d'accès lorsque le jeton actuel expire.

Paramètres d'expiration du jeton :

• expires_in : 300 secondes (5 minutes) à 172 800 secondes (2 jours)
• refresh_token_expires_in : 604 800 secondes (7 jours) à 7 776 000 secondes (90 jours)

Source : Documentation d'aide OAuth de Zendesk

Étape 4 : Faire des requêtes API authentifiées

Maintenant, utilisez votre jeton d'accès :

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

Ou en Python :

import requests

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

Ou en Node.js :

const axios = require('axios');

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

Lorsque le jeton d'accès expire, utilisez le jeton de rafraîchissement pour en obtenir un nouveau sans obliger l'utilisateur à se ré-autoriser.

Configurations d'étendue courantes par cas d'utilisation

Différentes intégrations ont besoin de différentes autorisations. Voici des configurations d'étendue typiques pour des scénarios courants.

Outils de reporting en lecture seule

Pour les tableaux de bord qui extraient les données des tickets sans apporter de modifications :

read

Ou plus précisément :

tickets:read users:read organizations:read

Cela donne à votre outil l'accès pour afficher les tickets, les utilisateurs et les organisations sans la possibilité de modifier quoi que ce soit.

Intégrations de synchronisation bidirectionnelle

Pour la synchronisation de Zendesk avec un CRM ou d'autres systèmes :

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

Cela vous permet de lire les données existantes et de renvoyer les mises à jour à Zendesk.

Gestion du contenu du Centre d'aide

Pour les outils qui gèrent les articles de la base de connaissances :

hc:read hc:write

Cela limite les autorisations au contenu du Centre d'aide uniquement, en gardant les tickets et les données utilisateur hors limites.

Portails orientés client

Pour les widgets intégrés où les utilisateurs finaux créent et consultent leurs propres tickets :

requests:read requests:write impersonate

L'étendue impersonate permet à votre application de créer des tickets au nom des utilisateurs finaux sans qu'ils aient besoin de comptes Zendesk.

Dépannage des erreurs d'authentification

Même avec la bonne configuration, les choses tournent mal. Voici comment résoudre les problèmes les plus courants.

Erreurs 403 Interdit

Une erreur 403 signifie que votre jeton est valide, mais que vous n'avez pas l'autorisation pour cette action.

Causes :

• Étendue requise manquante pour le point de terminaison
• Mauvais format d'étendue (tableau vs chaîne)
• Le rôle de l'utilisateur n'autorise pas cette action (par exemple, un agent essayant d'utiliser des points de terminaison réservés aux administrateurs)

Solution : Consultez la documentation de l'API pour connaître l'étendue requise du point de terminaison. Vérifiez que votre jeton a cette étendue en utilisant le point de terminaison Afficher le jeton.

Erreurs 401 Non autorisé

Une erreur 401 signifie que votre jeton n'est pas valide, a expiré ou est mal formé.

Causes :

• Le jeton a expiré (si vous avez défini une expiration)
• Le jeton a été révoqué par l'utilisateur ou un administrateur
• Le format du jeton est incorrect (préfixe "Bearer" manquant, par exemple)

Solution : Rafraîchissez le jeton si vous avez un jeton de rafraîchissement. Sinon, redirigez à nouveau l'utilisateur via le flux d'autorisation.

Erreurs OAuth courantes

Source : Documentation d'aide OAuth de Zendesk

Meilleures pratiques de sécurité pour l'authentification de l'API Zendesk

Faire fonctionner l'authentification est la première étape. La sécuriser est un processus continu.

Gestion des jetons

• Stocker les jetons chiffrés : Ne stockez jamais les jetons en texte clair et ne les validez pas dans les référentiels de code
• Implémenter la rotation automatique : Rafraîchissez les jetons avant qu'ils n'expirent pour éviter les interruptions de service
• Supprimer les jetons inutilisés : Révoquez les jetons pour les intégrations que vous n'utilisez plus
• Surveiller l'utilisation des jetons : Zendesk suit le moment où les jetons sont utilisés. Surveillez toute activité inattendue

Sélection de l'étendue

• Demander des étendues minimales : Ne demandez que les autorisations dont votre application a réellement besoin
• Vérifier les autorisations accordées : Vérifiez périodiquement les étendues de vos jetons
• Documenter les exigences d'étendue : Conservez un enregistrement de la raison pour laquelle chaque étendue est nécessaire à des fins de conformité

Sécurité de l'intégration

• Utiliser HTTPS pour toutes les requêtes : L'API Zendesk est uniquement SSL et nécessite TLS 1.2
• Implémenter PKCE pour les clients publics : Requis pour les applications mobiles et basées sur un navigateur
• Valider les paramètres d'état : Vérifiez toujours que le paramètre d'état correspond à ce que vous avez envoyé pour empêcher les attaques CSRF
• Prendre en charge SNI : Votre client HTTP doit prendre en charge l'extension TLS d'indication du nom de serveur

Source : Documents de sécurité et d'authentification Zendesk

Créer des intégrations Zendesk sécurisées avec eesel AI

Si tout cela vous semble beaucoup à gérer, vous n'êtes pas seul. L'authentification est l'une des parties les plus sujettes aux erreurs de la création d'intégrations Zendesk.

Chez eesel AI, nous gérons Zendesk OAuth en toute sécurité afin que vous n'ayez pas à vous soucier de la gestion des jetons, de la configuration de l'étendue ou de la logique de rafraîchissement. Notre intégration Zendesk est livrée avec des étendues préconfigurées qui suivent le principe du moindre privilège, le rafraîchissement automatique des jetons et la gestion des erreurs intégrée pour les problèmes d'authentification courants.

Nous offrons également un Agent IA qui peut travailler avec vos données Zendesk pour automatiser les flux de travail de support. Il se connecte via le même flux OAuth sécurisé, avec des étendues limitées à exactement ce dont l'automatisation a besoin.

Que vous le construisiez vous-même ou que vous utilisiez une plateforme comme la nôtre, la clé est de bien faire l'authentification dès le départ. Une base sécurisée facilite tout le reste.

Que vous le construisiez vous-même ou que vous utilisiez une plateforme comme la nôtre, la clé est de bien faire l'authentification dès le départ. Une base sécurisée facilite tout le reste.