Comment créer une application OAuth Zendesk : Un guide complet pour 2026

Si vous créez une intégration avec Zendesk, vous devrez éventuellement authentifier vos requêtes API. Bien que les jetons API fonctionnent pour les scripts simples, OAuth est la norme pour les applications de production qui accèdent aux données Zendesk au nom des utilisateurs. Il permet aux utilisateurs d'accorder des autorisations spécifiques sans partager leurs mots de passe, et il vous donne un contrôle précis sur ce à quoi votre application peut accéder.

Mais voici le problème : configurer OAuth peut sembler compliqué si vous ne l'avez jamais fait auparavant. Il y a des redirections, des codes d'autorisation, des portées et des secrets à gérer. Ce guide vous guide pas à pas tout au long du processus, de l'enregistrement de votre application à la réalisation de votre premier appel API authentifié.

Si vous recherchez une approche plus simple, eesel AI gère automatiquement l'authentification Zendesk. Vous connectez votre compte une seule fois, et nous gérons le flux OAuth en arrière-plan. Mais si vous devez créer une intégration personnalisée, continuez à lire.

Ce dont vous aurez besoin

Avant de commencer, assurez-vous d'avoir :

• Un compte Zendesk sur le plan Suite Growth ou supérieur, ou le plan Support Professional ou supérieur
• Un accès administrateur à votre instance Zendesk (ou quelqu'un qui peut l'accorder)
• Une compréhension de base des concepts OAuth 2.0 (codes d'autorisation, jetons d'accès, redirections)
• Un environnement de développement où vous pouvez tester le flux OAuth

Si vous faites juste des expériences, Zendesk propose des comptes d'essai pour le développement. Vous pouvez également consulter la documentation officielle de Zendesk OAuth pour les derniers détails sur les flux d'authentification et les points de terminaison.

Étape 1 : Enregistrez votre client OAuth dans Zendesk

La première étape consiste à informer Zendesk de votre application. Cela crée un client OAuth que les utilisateurs autorisent lorsqu'ils connectent votre application.

Accédez à la section Clients OAuth :

1. Connectez-vous à Zendesk et accédez au Centre d'administration (cliquez sur l'icône d'engrenage dans la barre latérale)
2. Sélectionnez Applications et intégrations dans la barre latérale de gauche
3. Cliquez sur API → Clients OAuth
4. Cliquez sur Ajouter un client OAuth sur le côté droit

Renseignez les détails du client :

• Nom : Un nom d'affichage pour votre application. Les utilisateurs voient cela lorsqu'ils autorisent votre application.
• Description : Facultatif, mais aide les utilisateurs à comprendre ce que fait votre application
• Entreprise : Le nom de votre entreprise
• Logo : Facultatif. Téléchargez une image carrée (JPG, GIF ou PNG) qui représente votre application
• Type de client : Choisissez entre Public ou Confidentiel
  • Confidentiel : Pour les applications côté serveur où vous pouvez stocker en toute sécurité le secret client
  • Public : Pour les applications mobiles ou les applications JavaScript où le secret pourrait être exposé. Ceux-ci doivent utiliser PKCE.
• URL de redirection : Les URL où Zendesk enverra les utilisateurs après qu'ils auront autorisé votre application. Doit être HTTPS (sauf pour localhost pendant le développement). Ajoutez plusieurs URL sur des lignes séparées si nécessaire.

Enregistrez vos informations d'identification :

Après avoir cliqué sur Enregistrer, Zendesk génère un ID client (appelé « Identifiant ») et un Secret client. Copiez les deux immédiatement, le secret n'est affiché qu'une seule fois. Si vous le perdez, vous devrez en générer un nouveau.

Étape 2 : Choisissez le bon flux OAuth

Zendesk prend en charge deux principaux types d'autorisation OAuth 2.0. Choisissez celui qui correspond à votre cas d'utilisation.

Le flux de code d'autorisation est destiné aux applications destinées aux utilisateurs. Lorsqu'un utilisateur souhaite connecter votre application à son compte Zendesk, vous le redirigez vers la page d'autorisation de Zendesk. Il se connecte, approuve les autorisations et Zendesk le renvoie à votre application avec un code d'autorisation. Votre serveur échange ce code contre un jeton d'accès.

Ce flux prend en charge les jetons d'actualisation, vous pouvez donc obtenir de nouveaux jetons d'accès sans demander à l'utilisateur de se ré-autoriser. Les jetons d'accès expirent (vous pouvez définir cela entre 5 minutes et 2 jours), mais les jetons d'actualisation durent plus longtemps (7 à 90 jours).

Le flux d'informations d'identification du client est destiné à l'authentification de machine à machine. Aucun utilisateur n'est impliqué. Votre application utilise son ID client et son secret pour obtenir directement un jeton d'accès. Cela fonctionne bien pour les services backend qui doivent accéder aux données Zendesk selon un calendrier.

PKCE (Proof Key for Code Exchange) ajoute de la sécurité pour les clients publics. Si vous créez une application mobile ou une application monopage où vous ne pouvez pas stocker en toute sécurité un secret client, utilisez PKCE avec le flux de code d'autorisation. Il empêche les attaques d'interception de code d'autorisation.

Étape 3 : Configurez les portées OAuth

Les portées contrôlent ce à quoi votre application peut accéder dans Zendesk. Soyez précis, ne demander que les autorisations dont vous avez réellement besoin respecte le principe du moindre privilège et rend les utilisateurs plus susceptibles de faire confiance à votre application.

Zendesk propose trois principaux types de portées :

• read : Accès aux points de terminaison GET. Inclut l'autorisation de charger 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 de ressources.
• impersonate : Permet aux administrateurs d'effectuer des requêtes API au nom des utilisateurs finaux.

Vous pouvez également demander des portées spécifiques aux ressources pour un contrôle plus précis :

• tickets:read ou tickets:write
• users:read ou users:write
• organizations:read ou organizations:write
• macros:read ou macros:write
• triggers:read ou triggers:write

Par exemple, si votre application n'a besoin que de lire les tickets et de mettre à jour les profils d'utilisateurs, demandez tickets:read users:write au lieu d'un accès read write général.

Important : Les autorisations réelles d'un utilisateur dans Zendesk s'appliquent toujours. Même si votre portée OAuth autorise l'écriture de tickets, un utilisateur avec un accès en lecture seule ne peut pas créer de tickets via votre application.

Étape 4 : Mettez en œuvre le flux d'autorisation

Voici comment mettre en œuvre le flux de code d'autorisation, l'approche la plus courante pour les applications Web.

Envoyez les utilisateurs au point de terminaison d'autorisation :

Redirigez les utilisateurs vers cette URL avec les paramètres requis :

https://{subdomain}.zendesk.com/oauth/authorizations/new

Incluez ces paramètres de requête :

• response_type=code (obligatoire)
• client_id={your_client_id} (obligatoire)
• redirect_uri={your_redirect_url} (obligatoire, doit correspondre à ce que vous avez enregistré)
• scope={requested_scopes} (obligatoire, séparé par des espaces)
• state={random_string} (recommandé, empêche les attaques CSRF)

Exemple d'URL :

https://yourcompany.zendesk.com/oauth/authorizations/new?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=read%20write&state=abc123

Gérez la redirection :

Une fois que l'utilisateur approuve ou refuse l'accès, Zendesk le redirige vers votre redirect_uri avec :

• Un code d'autorisation : ?code=7xqwtlf3rrdj8uyeb1yf&state=abc123
• Une erreur : ?error=access_denied&error_description=User+denied+access

Vérifiez que le paramètre state correspond à ce que vous avez envoyé, puis extrayez le code. Les codes d'autorisation expirent après 120 secondes, alors échangez-les immédiatement.

Échangez le code contre des jetons :

Effectuez une requête POST au point de terminaison de jeton de Zendesk :

import requests

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'authorization_code',
        'code': authorization_code,
        'client_id': client_id,
        'client_secret': client_secret,
        'redirect_uri': redirect_uri,
        'scope': 'read',
        'expires_in': 172800,  # 2 days
        'refresh_token_expires_in': 7776000  # 90 days
    }
)

tokens = response.json()
access_token = tokens['access_token']
refresh_token = tokens['refresh_token']

Stockez les deux jetons en toute sécurité. Le jeton d'accès est ce que vous utiliserez pour les appels API. Le jeton d'actualisation vous permet d'obtenir de nouveaux jetons d'accès lorsque le jeton actuel expire.

Étape 5 : Utilisez les jetons d'accès dans les requêtes API

Avec un jeton d'accès, vous pouvez maintenant effectuer des requêtes authentifiées à l'API Zendesk.

Incluez le jeton dans l'en-tête Authorization :

Authorization: Bearer {access_token}

Exemple de requête :

import requests

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

Gérez l'expiration du jeton :

Lorsqu'un jeton d'accès expire, les requêtes API renvoient un statut 401 avec cette erreur :

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}

Utilisez votre jeton d'actualisation pour obtenir un nouveau jeton d'accès :

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': client_id,
        'client_secret': client_secret,
        'scope': 'read'
    }
)

new_tokens = response.json()

Si le jeton d'actualisation a également expiré, vous devrez renvoyer l'utilisateur dans le flux d'autorisation.

Problèmes courants et dépannage

Erreurs « URI de redirection non valide » : L'URL de redirection dans votre requête d'autorisation doit correspondre exactement à l'une des URL enregistrées dans votre client OAuth. Vérifiez les barres obliques de fin, http vs https et les différences de sous-domaine.

Autorisation de portée refusée : N'oubliez pas que les portées OAuth sont limitées par les autorisations Zendesk réelles de l'utilisateur. Un agent avec un accès en lecture seule ne peut pas écrire de tickets même si votre portée OAuth le permet.

Secret client affiché uniquement partiellement : Zendesk n'affiche le secret complet qu'une seule fois, immédiatement après la création. Si vous ne l'avez pas copié, vous devrez en générer un nouveau dans les paramètres du client OAuth.

Test avec localhost : Zendesk autorise http://localhost et http://127.0.0.1 comme URL de redirection pour le développement. Assurez-vous d'enregistrer l'URL exacte, y compris le port (par exemple, http://localhost:3000/callback).

Code d'autorisation expiré : Les codes ne sont valides que pendant 120 secondes. Si votre utilisateur met trop de temps à autoriser, ou s'il y a un délai dans votre échange de code, vous obtiendrez une erreur. Redémarrez le flux.

Bonnes pratiques de sécurité

Stockez les secrets en toute sécurité : Ne codez jamais en dur les secrets client dans votre code source ou ne les validez pas dans le contrôle de version. Utilisez des variables d'environnement ou un service de gestion des secrets. La fiche de référence OWASP OAuth fournit des recommandations de sécurité supplémentaires pour les implémentations OAuth.

Utilisez HTTPS partout : Toutes les URL de redirection en production doivent utiliser HTTPS. La seule exception est localhost pendant le développement.

Mettez en œuvre PKCE pour les clients publics : Si vous créez une application mobile ou une application basée sur un navigateur où le secret pourrait être exposé, utilisez PKCE. Générez un vérificateur de code, hachez-le pour créer un défi de code et envoyez le défi avec votre requête d'autorisation.

Définissez une expiration de jeton raisonnable : Les jetons de courte durée sont plus sécurisés. Pour la plupart des applications, 24 heures est un bon équilibre entre sécurité et commodité.

Faites pivoter régulièrement les informations d'identification : Générez périodiquement de nouveaux secrets client et mettez à jour vos applications. Si vous pensez qu'un secret a été compromis, faites-le pivoter immédiatement.

Validez le paramètre d'état : Vérifiez toujours que le paramètre d'état dans la redirection correspond à ce que vous avez envoyé. Cela empêche les attaques CSRF où des sites malveillants incitent les utilisateurs à autoriser un accès indésirable.

Évitez la complexité d'OAuth avec eesel AI

La création d'une intégration OAuth personnalisée prend du temps et nécessite une maintenance continue. Vous devez gérer le flux d'autorisation, l'actualisation des jetons, les cas d'erreur et les mises à jour de sécurité. Pour de nombreuses équipes, ce n'est pas la meilleure utilisation du temps d'ingénierie.

eesel AI offre un chemin plus simple. Notre agent d'IA se connecte à votre compte Zendesk en un seul clic. Nous gérons automatiquement l'authentification OAuth, afin que vous puissiez vous concentrer sur ce qui compte : créer des automatisations qui résolvent réellement les problèmes.

Au lieu d'écrire du code pour échanger des codes d'autorisation et actualiser des jetons, vous pouvez :

• Former une IA sur vos articles du centre d'aide et vos tickets passés
• Configurer des automatisations qui résolvent les tickets de bout en bout
• Transférer les problèmes complexes à des humains avec des règles en anglais simple
• Exécuter des simulations sur des données historiques avant de passer en direct

Si vous créez une intégration profondément personnalisée, OAuth peut être le bon choix. Mais si vous avez besoin d'une automatisation du support basée sur l'IA sans les frais généraux d'ingénierie, essayez eesel AI.