Mon édition

Disponible avec toutes les éditions Suite Disponible avec toutes les éditions Support

Accès rapide : Centre d’administration > Applications et intégrations > API > API Zendesk

Vous pouvez utiliser OAuth 2 pour authentifier toutes les demandes API de votre application vers Zendesk. OAuth permet à votre application d’accéder aux données Zendesk de façon sécurisée sans avoir à stocker ni à utiliser les mots de passe des utilisateurs Zendesk, qui sont des informations sensibles.

Pour utiliser l’authentification OAuth, vous devez enregistrer votre application auprès de Zendesk. Vous devez aussi d’ajouter certaines fonctionnalités à votre application pour qu’elle prenne en charge le flux d’autorisation OAuth.

Sujets abordés dans cet article :

  • Enregistrement de votre application auprès de Zendesk
  • Mise en œuvre d’un flux d’autorisation OAuth dans votre application

Articles connexes :

  • Pour un didacticiel expliquant la création d’une application Web mettant en œuvre le flux d’autorisation OAuth, consultez Building an OAuth web app.
  • Pour savoir comment mettre en œuvre un flux d’authentification OAuth dans les applications Zendesk, consultez l’article portant sur l’ajout d’une authentification OAuth tierce à une application Support.
  • Si vous n’avez pas besoin que les utilisateurs accordent à votre application l’accès à leurs comptes, vous pouvez malgré tout utiliser les tokens OAuth pour authentifier les demandes API. Consultez Creating and using OAuth tokens with the API.

Enregistrement de votre application auprès de Zendesk

Vous devez enregistrer votre application pour générer des valeurs de connexion OAuth que votre application utilisera pour authentifier les appels API vers Zendesk.

Remarque – Cette section explique comment configurer un client OAuth pour les utilisateurs d’un seul client Zendesk. Si votre application communique non seulement avec un compte Zendesk, mais également avec une multitude d’autres comptes, vous pouvez demander un client OAuthglobal. Un client OAuth global est une méthode plus sûre et plus propre d’effectuer l’authentification API avec plusieurs instances Zendesk. Pour en savoir plus, consultez l’article portant sur la configuration d’un client OAuth global.

Pour enregistrer votre application

  1. Dans le Centre d’administration, cliquez sur Applications et intégrations dans la barre latérale, puis sélectionnez API > API Zendesk.
  2. Activez l’onglet Clients OAuth à la page API Zendesk, puis cliquez sur Ajouter un client OAuth sur la droite de la liste des clients OAuth.
  3. Remplissez les champs suivants pour créer un client :
    • Nom du client - saisissez un nom pour votre application. Il s’agit du nom que verront les utilisateurs lorsqu’il leur sera demandé d’accorder l’accès à votre application, et lorsqu’ils consulteront la liste des applications tierces qui ont accès à leur Zendesk.
    • Description - facultatif. Il s’agit d’une brève description de votre application que verront les utilisateurs lorsqu’il leur sera demandé d’y accorder l’accès.
    • Société - facultatif. Il s’agit du nom de la société que verront les utilisateurs lorsqu’il leur sera demandé d’accorder l’accès à votre application. Le nom les aidera à comprendre à qui ils accordent l’accès.
    • Logo - facultatif. Il s’agit du logo que verront les utilisateurs lorsqu’il leur sera demandé d’accorder l’accès à votre application. L’image peut-être aux formats JPG, GIF ou PNG. Pour un résultat optimal, téléchargez une image carrée. Elle sera redimensionnée pour la page d’autorisation.
    • Identifiant unique - le champ est rempli automatiquement avec une version reformatée du nom que vous avez saisi pour votre application. Vous pouvez le modifier si vous le souhaitez.
    • Type de client - Public ou Confidentiel. Les clients OAuth publics sont des applications qui s’exécutent dans des environnements dans lesquels leurs identifiants ne peuvent pas être stockés de façon sécurisée, comme les applications Web ou mobiles. Ces clients doivent utiliser PKCE. Les clients OAuth confidentiels s’exécutent sur des serveurs sécurisés où les identifiants peuvent être conservés de façon sécurisée. Ces clients peuvent utiliser PKCE, le secret client ou les deux. Consultez Types de clients OAuth.
    • URL de redirection - saisissez l’URL ou les URL que Zendesk doit utiliser pour envoyer la décision de l’utilisateur d’accorder l’accès à votre application. Les URL doivent être absolues et non relatives, sécurisées (https, sauf si hôte local ou 127.0.0.1), et séparées par de nouvelles lignes.
  4. Cliquez sur Enregistrer.

    Une fois la page actualisée, un nouveau champ Secret prérempli apparaît en bas de l’écran. Il s’agit de la valeur « client_secret » spécifiée dans la spécification OAuth2.

  5. Copiez la valeur Secret dans votre presse-papier et conservez-la en lieu sûr. Remarque – Les caractères peuvent dépasser la largeur du champ de texte, veillez donc à tout sélectionner avant de copier.
    Important : pour des raisons de sécurité, votre valeur secrète n’est affichée intégralement qu’une seule fois. Après avoir cliqué sur Enregistrer, vous ne verrez que les neuf premiers caractères.
  6. Cliquez sur Enregistrer.

Utilisez l’identifiant unique et la valeur secrète dans votre application, comme décrit dans le sujet suivant.

Types de clients OAuth

Les clients OAuth Zendesk incluent une propriété kind qui est transférée lors de la création du client OAuth et peuvent avoir l’une des valeurs suivantes :

  • Public : Les clients OAuth publics sont des applications qui s’exécutent dans des environnements dans lesquels leurs identifiants ne peuvent pas être stockés de façon sécurisée, comme les applications Web ou mobiles. Ces clients doivent utiliser PKCE.
  • Confidentiel : Les clients OAuth confidentiels s’exécutent sur des serveurs sécurisés où les identifiants peuvent être conservés de façon sécurisée. Ces clients peuvent utiliser PKCE, le secret client ou les deux.

Pour en savoir plus, consultez Types de clients.

Le type de client OAuth Zendesk s’applique uniquement au système de gestion des tickets Zendesk Support. Il n’est pas pris en charge dans Chat, les conversations ou Sell.

Pour les clients OAuth Zendesk existants, la propriété kind est définie sur unknown. Ces clients ne changent pas jusqu’à ce que la propriété kind soit mise à jour sur public ou confidential. Pour les nouveaux clients OAuth créés dans le Centre d’administration, la propriété kind doit être définie pendant la création.

Remarque – Si vous utilisez un client OAuth Zendesk existant et projetez de mettre à jour la propriété kind sur public, vous devez implémenter PKCE. Sinon, le client ne fonctionnera pas, car PKCE sera immédiatement requis.

Pour les nouveaux clients OAuth créés dans le Centre d’administration, la propriété kind doit être définie. La propriété kind n’est pas obligatoire pour les clients OAuth créé avec le point de terminaison api/v2/oauth/clients endpoint, mais Zendesk recommande de l’inclure.

Mise en œuvre d’un flux d’autorisation OAuth dans votre application

Zendesk prend en charge le flux d’octroi de code d’autorisation pour l’obtention des tokens d’accès. Ce flux est appelé flux d’octroi de code d’autorisation, car vous avez besoin d’un code d’autorisation pour pouvoir demander un token d’accès. Les autres flux d’octroi ont été abandonnés.

Le flux n’utilise pas de token d’actualisation. Le token d’accès n’expire pas.

Pour mettre en œuvre le flux d’octroi de code d’autorisation, vous devez ajouter la fonctionnalité suivante à votre application :

  • Étape 1 - Dirigez l’utilisateur vers la page d’autorisation de Zendesk
  • Étape 2 - Traitez la décision d’autorisation de l’utilisateur
  • Étape 3 - Obtenez un token d’accès auprès de Zendesk
  • Étape 4 - Utilisez le token d’accès dans les appels API

Pour un didacticiel expliquant la création d’une application Web mettant en œuvre le flux d’autorisation OAuth, consultez Building an OAuth web app.

La méthode d’octroi d’un code d’autorisation prend en charge Proof Key for Code Exchange (PKCE), qui ajoute une couche de sécurité supplémentaire. Pour en savoir plus, consultez la section sur l’utilisation de PKCE pour rendre les tokens d’accès OAuth Zendesk encore plus sûrs dans la documentation pour les développeurs.

Étape 1 - Dirigez l’utilisateur vers la page d’autorisation de Zendesk

L’application doit d’abord diriger l’utilisateur vers la page d’autorisation de Zendesk. La page demande à l’utilisateur d’autoriser votre application à accéder à Zendesk en votre nom. Lorsque l’utilisateur a pris sa décision, Zendesk renvoie le choix et d’autres éléments d’information à votre application.

Pour diriger l’utilisateur vers la page d’autorisation de Zendesk

Ajoutez un lien ou un bouton dans votre application pour diriger l’utilisateur vers l’URL suivante :

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

où {subdomain} est votre sous-domaine Zendesk. Vous pouvez utiliser une requête POST ou GET. Incluez les paramètres suivants :

  • response_type - obligatoire. Zendesk renvoie un code d’autorisation dans la réponse ; vous devez donc spécifier code comme type de réponse. Exemple : response_type=code.
  • redirect_uri - obligatoire. L’URL que Zendesk doit utiliser pour envoyer la décision de l’utilisation pour accorder l’accès à votre application. L’URL doit être absolue (pas relative). Elle doit en outre être sécurisée (https), sauf si vous utilisez localhost ou 127.0.0.1.
  • client_id - obligatoire. L’identifiant unique que vous avez obtenu lorsque vous avez enregistré votre application auprès de Zendesk. Voir la section ci-dessus.
  • scope - obligatoire. Liste séparée par des espaces des valeurs qui contrôlent l’accès aux ressources Zendesk. Vous pouvez demander un accès de type read, write ou impersonate à toutes les ressources ou à des ressources spécifiques. Consultez Définition de la portée.
  • state - chaîne arbitraire incluse dans la réponse de Zendesk une fois que l’utilisateur a décidé ou non d’octroyer l’accès. Vous pouvez utiliser le paramètre pour vous protéger contre les attaques intersite (CSRF). Lors d’une attaque de type CSRF, l’utilisateur final est incité à cliquer sur un lien qui lance une action dans une application Web où l’utilisateur est toujours authentifié. Pour se protéger contre ce type d’attaque, ajoutez une valeur au paramètre state et validez-la lorsqu’elle revient.
  • code_challenge - Obligatoire si vous utilisez PKCE. Une chaîne représentant un défi de code dérivé d’un vérificateur de code. Consultez la section sur la génération de la valeur code_challenge dans la documentation pour les développeurs.
  • code_challenge_method - Obligatoire si vous utilisez PKCE. La méthode utilisée pour dériver le défi de code. Spécifiez "S256" comme valeur.

Veillez à coder les paramètres dans l’URL.

Exemple de requête GET

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

La page d’autorisation de Zendesk s’ouvre dans le navigateur de l’utilisateur final. Une fois que l’utilisateur a pris sa décision, Zendesk envoie la décision à l’URL de redirection que vous avez spécifiée dans la demande.

Définition de la portée

Vous devez spécifier une portée pour contrôler l’accès de l’application aux ressources Zendesk. La valeur read permet à l’application d’accéder aux points finaux GET. Cela inclut la permission de transférer les ressources connexes. La valeur write permet à l’application d’accéder aux points finaux POST, PUT et DELETE pour créer, mettre à jour et supprimer des ressources.

Pour en savoir plus au sujet de la portée, consultez l’article sur les tokens OAuth pour les types d’octroi.

La valeur impersonate permet à un administrateur Zendesk de faire des demandes pour le compte des utilisateurs finaux. Consultez Faire des demandes d’API pour le compte des utilisateurs finaux.

Par exemple, le paramètre suivant accorde à une application l’accès en lecture à toutes les ressources :

"scope": "read"

Le paramètre suivant accorde l’accès en lecture et écriture à toutes les ressources :

"scope": "read write"

Vous pouvez affiner la portée aux ressources suivantes :

  • tickets
  • utilisateurs
  • journaux d’audit (lecture seule)
  • organisations
  • centre d’aide
  • applications
  • déclencheurs
  • automatismes
  • cibles
  • webhooks
  • zis

La syntaxe est la suivante :

"scope": "resource:scope"

Par exemple, le paramètre suivant limite une application à la lecture des tickets :

"scope": "tickets:read"

Pour accorder l’accès en lecture et écriture à une ressource, spécifiez les deux valeurs :

"scope": "users:read users:write"

Pour accorder l’accès en écriture à une seule ressource, par exemple les organisations, et l’accès en lecture à tout le reste :

"scope": "organizations:write read"

Étape 2 - Traitez la décision d’autorisation de l’utilisateur

Votre application doit traiter la réponse de Zendesk, qui lui indique ce qu’a décidé l’utilisateur. Les informations se trouvent dans les paramètres d’URL de l’URL de redirection.

Si l’utilisateur a décidé d’accorder l’accès à l’application, l’URL de redirection contient un code d’autorisation. Exemple :

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

Le code d’autorisation n’est valable que 120 secondes.

Si l’utilisateur a décidé de ne pas accorder l’accès à l’application, l’URL de redirection contient les paramètres error et error_description qui informent l’application que l’utilisateur a refusé l’accès :

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Utilisez ces valeurs pour contrôler le flux de votre application. Si l’URL contient le paramètre code, obtenez un token d’accès auprès de Zendesk, comme décrit dans la section suivante. Il s’agit du token à inclure dans les appels API à Zendesk.

Étape 3 - Obtenez un token d’accès auprès de Zendesk

Si votre application a reçu un code d’autorisation de Zendesk en réponse à l’utilisateur octroyant l’accès, votre application peut l’échanger contre un token d’accès. Pour obtenir le token d’accès, lancez une requête POST au point final suivant :

https://{subdomain}.zendesk.com/oauth/tokens
Remarque – Ne confondez pas ce point de terminaison avec le point de terminaison Create token dans l’API Tokens OAuth. Même si ces deux points de terminaison renvoient des tokens d’accès OAuth valides, ils ne partagent pas le même chemin, le même format JSON ni les mêmes paramètres de demande.

Incluez les paramètres suivants obligatoires dans la requête :

  • grant_type - spécifiez « authorization_code » comme valeur.
  • code - utilisez le code d’autorisation que vous avez reçu de Zendesk après octroi de l’accès par l’utilisateur.
  • client_id - utilisez l’identifiant unique spécifié dans un client OAuth dans l’interface d’administration Support (Admin > Canaux > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.
  • secret - utilisez le secret spécifié dans un client OAuth dans l’interface d’administration Support (Admin > Canaux > API > Clients OAuth). Consultez Enregistrement de votre application auprès de Zendesk.

    Si vous utilisez les paramètres PKCE code_challenge et code_verifier, client_secret n’est pas obligatoire. Vous pouvez utiliser cette caractéristique pour effectuer la migration à partir du flux d’octroi implicite, qui n’est plus conseillé à cause d’inquiétudes portant sur la sécurité. Consultez la section portant sur l’utilisation de PKCE pour effectuer la migration à partir du flux d’octroi implicite dans la documentation pour les développeurs.

  • redirect_uri - la même URL de redirection que celle de l’étape 1. À des fins d’identification uniquement.
  • scope - consultez Définition de la portée.
  • code_verifier - Obligatoire si vous utilisez PKCE. La chaîne utilisée pour générer la valeur code_challenge. Consultez la section sur la génération de la valeur code_challenge dans la documentation pour les développeurs.

La requête doit être dirigée sur un site https et les propriétés doivent être au format JSON. Si vous utilisez une application personnalisée ou tierce pour effectuer la demande API, consultez sa documentation pour connaître le format approprié pour les valeurs des propriétés.

Utilisation de curl

curl https://{subdomain}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "authorization_code", "code": "{your_code}",
    "client_id": "{your_client_id}", "client_secret": "{your_client_secret}", 
    "redirect_uri": "{your_redirect_url}", "scope": "read" }' \
  -X POST

Exemple de réponse

Status: 200 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "token_type": "bearer",
  "scope":"read"
}

Étape 4 - Utilisez le token d’accès dans les appels API

L’application peut utiliser le token d’accès pour effectuer des appels d’API. Incluez le token dans un en-tête d’autorisation HTTP avec la demande, comme suit :

Authorization: Bearer {a_valid_access_token}

Par exemple, une requête curl pour répertorier des tickets ressemblerait à ce qui suit :

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