Génération d'un jeton API REST pour les comptes de conversation intégrés

Aperçu

Dans le cadre des modifications apportées aux clients du support qui utilisent Chat, il ne sera plus possible de s’authentifier auprès de l’API REST à l’aide d’une authentification de base. Vous devrez utiliser OAuth pour générer un jeton pour authentifier les demandes.

Cela peut s'avérer un peu difficile lorsque vous l'essayez pour la première fois. Examinons donc un exemple de génération manuelle du jeton. Ce jeton peut être utilisé dans les appels d'API pour lire et écrire des données via l'API REST. Si vous créez une application, vous devez écrire la génération de jeton dans votre application, mais ces étapes à suivre à la main sont utiles pour voir à l'intérieur du flux.

Conditions

Ce didacticiel est destiné aux comptes de conversation intégrés auxquels toutes les modifications mentionnées dans l'article ci-dessus ont été appliquées. Ceci est en cours de déploiement graduel, de sorte que certains comptes peuvent en avoir besoin avant les autres. Si vous n'êtes pas sûr si votre compte a reçu toutes les modifications, n'hésitez pas à contacter notre équipe d'assistance qui pourra le confirmer pour vous.

Remarque : un effet secondaire des changements sur les comptes est que les jetons OAuth devront être recréés. Si vous terminez ce tutoriel avant que les modifications aient atteint votre compte, vous devrez ré-exécuter les étapes par la suite.

Procédure

Le flux d'octroi "Code d'autorisation" OAuth comprend les étapes suivantes :

1. Octroyer l'accès à l'application.
2. Obtenir une code autorisation.
3. Faire une demande avec le code autorisation.
4. Obtenir un jeton autorisation.

Le code autorisation de l'étape 2 est uniquement valide pour l'utiliser dans l'étape 3 pendant une courte période, il est donc recommandé de vous préparer pour toutes les étapes avant le début du processus. Voici l'ordre que je vais suivre au fur et à mesure du processus.

Création de l'API client

Tout d'abord, nous avons besoin d'un API client. Aller à Zendesk Chat > Compte > API et cliquez sur le bouton Ajouter Client API. Saisissez un nom de votre choix pour le client et l'entreprise, et pour la Redirection URL saisissez http://localhost:8080. Cela devrait ressembler à ceci:

Cliquez sur Créer un client API pour terminer la configuration. Vous verrez une fenêtre pop-up avec l'ID client et secret. Très important : Le client secret n'est montré qu'une seule fois, alors notez-le bien pour utilisation ultérieure. Cela ressemblera à ceci :

Maintenant que notre Client API est prêt, notez bien votre ID et votre secret avant de cliquer sur "Ok, j'ai compris". Nous sommes prêts à commencer avec le flux OAuth.

Finalisation du flux OAuth

Notez bien vos détails jusqu'à présent, qui devraient être comme ci-dessous. Je vais utiliser des données fictives au lieu de vrais données - rappelez-vous que votre ID client et secret doivent être traités avec la plus grande sécurité, puisqu'ils sont essentiellement des mots de passe, donnant un accès complet aux informations sur votre Chat.

• ID client: CLIENT_ID
• Secret Client: CLIENT_SECRET
• Redirect URI: http://localhost:8080
• Sous-domaine: votre sous-domaine Zendesk; par exemple, si votre compte est à niall.zendesk.com, cette valeur est: "niall"
• Code d'autorisation: nous n'avons pas encore cette donnée

1. Préparer la première URL

Ici, nous allons créer une URL pour demander un code autorisation. Vous devrez aller à https://www.zopim.com/oauth2/authorizations/new, et ajouter quelques paramètres de requête pour faire passer certaines des informations ci-dessus. Cette fois-ci, nous avons besoin de:

• response_type: ceci sera toujours "code"
• redirect_uri: c'est là où nous allons être redirigés après avoir accordé l'accès, http://localhost:8080 pour notre tutoriel
• client_id : à vous seul(e), comme écrit précédemment
• portée: quel sera le niveau d'accès pour ce token, nous allons choisir "lire et écrire"
• sous-domaine : votre sous-domaine Zendesk

Mettre le tout ensemble, et l'encodage URL vous donnera une URL finale, qui ressemblera à ceci :

https://www.zopim.com/oauth2/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

avec CLIENT-ID et SUBDOMAIN, étant les seules différences pour votre propre URL.

2. Préparer l'appel cURL

Avant de visiter cet URL, créons l'appel cURL que nous allons poursuivre. Cette fois-ci, nous aurons besoin de :

• grant_type: ce sera toujours authorization_code
• code: celui-ci sera obtenu après avoir permis l'accès à partir de l'URL
• client-id: votre ID client
• client_secret : votre secret client
• redirect-uri: même chose que la dernière étape - http://localhost:8080
• portée: la même que la dernière étape - lire et écrire

Quand nous mettons tout cela ensemble, nous obtenons une Commande qui devrait ressembler à :

curl https://www.zopim.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \ -X POST

Rappel: vous devriez déjà avoir CLIENT_ID et CLIENT_SECRET maintenant, mais nous n'avons pas encore AUTH_CODE.

3. Obtenir votre code autorisation

Maintenant, allez vers l'URL que nous avons généré en étape 1. Vous allez voir une page comme suit:

Cliquez sur Autoriser l'accès, et vous serez redirigé vers la redirection URL. Cela ressemblera à une page cassée, mais ce qui est important, c'est de chercher dans l'URL pour voir quel est le code autorisation, par ex., tout ce qui vient après? code =

Copier ce code, et préparons-nous pour la dernière étape !

4. Faire l'appel cURL pour obtenir votre token

Pour en revenir à l'appel cURL que nous avons construit dans l'étape 2, qui ressemble à ceci:

curl https://www.zopim.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \ -X POST

remplacer AUTH-CODE avec le code de l'étape 3, et exécuter la commande depuis une application "terminal". Vous recevrez une réponse sous la forme d'un objet JSON comme ceci :

{ "access_token": "TOKEN", "token_type": "Bearer", "refresh_token": "REFRESH_TOKEN", "scope": "read write" }

5. Testez le nouveau token

Il est toujours recommandé de tester pour confirmer que tout marche comme vous le voulez, nous pouvons le faire maintenant. L'appel le plus facile à faire est juste un simple GET to /api/v2/chats, pour voir vos informations compte:

curl https://www.zopim.com/api/v2/chats -H "Authorization: Bearer TOKEN"

remplacement du TOKEN avec celui récupéré dans l'étape 4.

Approche alternative pour obtenir un token

L'approche ci-dessus utilise le flux d'octroi "Code d'autorisation" OAuth. Une autre approche consiste à utiliser le flux d'octroi "Implicite" OAuth. Au lieu d'utiliser response_type de 'code', vous utiliserez un type de réponse "token". Si vous le faites manuellement, cette approche comporte moins d'étapes et peut s'avérer plus pratique.

1. Suivez la même étape "Création du client API" ci-dessus

2. Recueillez des informations similaires à celles ci-dessus

• ID client: CLIENT_ID
• URL indirecte: http://localhost:808080
• Sous-domaine Zendesk

3. Formatez l'URL ci-dessous avec vos propres CLIENT_ID et SUBDOMAIN, collez-le dans un nouvel onglet de navigateur et appuyez sur Entrée.

https://www.zopim.com/oauth2/authorizations/new?response_type=token&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

Notes :

• Si le client Chat OAuth n'a qu'une valeur d'URL de redirection, la transmission d'une valeur redirect_uri est facultative. Le système utilisera par défaut la valeur d'URL de redirection du client OAuth.
• Si le client OAuth a plus d'une valeur d'URL de redirection, il faut passer une valeur de redirect_uri
• Si une valeur de redirect_uri est transmise, elle doit être codée par URL.

4. L'appel sera effectué, vous demandant éventuellement de vous connecter et de sélectionner « Autoriser » (comme à l'étape 3 de la section précédente).

Si l'appel réussit, le champ d'adresse de votre navigateur contiendra votre nouveau jeton OAuth (renvoyé en tant que valeur access_token).

Malgré le message d'erreur apparaissant dans la fenêtre principale du navigateur, si 'access_token' est renvoyé dans le champ URL du navigateur, ça a marché !

Informations supplémentaires

Client_type confidentiel

Pour les paramètres API pour les administrateurs et agents, comme les mesures de rapports, vous devrez configurer le client_type comme "confidentiel". Par défaut, cette valeur est définie sur "public". Cela ne peut se faire que via l'API, et peut être réalisé de la manière suivante:

1. Obtenir identifiant du client

Nous aurons tout d'abord besoin de l'identifiant de votre nouveau client. Vous pouvez l'obtenir en utilisant votre nouveau token, avec l'appel suivant :

curl https://www.zopim.com/api/v2/oauth/clients -H "Authorization: Bearer TOKEN"

qui affichera tous vos clients. Vous ne pouvez en avoir qu'un. Si vous avez plusieurs, vous devriez choisir celui que vous souhaitez mettre à jour et noter son identifiant.

2. Mettre à jour le client_type

Maintenant que vous avez l'identifiant, vous pouvez exécuter l'appel cURL ci-dessous pour mettre à jour la propriété client_type :

curl https://www.zopim.com/api/v2/oauth/clients/ID -d '{"client_type": "confidential"}' 
\ -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

Une fois que cela est terminé, votre token peut être utilisé pour des paramètres d'arrêt limités.