1. Comment fonctionne l'authentification dans Ermeo ?
L'API d'Ermeo repose sur un système d'authentification très courant. Afin d'authentifier les requêtes envoyées à notre API, un en-tête spécifique est nécessaire : Authorization. La valeur de l'en-tête Authorization est ce qu'on appelle le access_token. Ainsi, chaque requête envoyée à notre API doit contenir cet en-tête avec le access_token correct pour accéder aux données d'Ermeo.
2. Comment récupérer un access_token avec votre nom d'utilisateur et mot de passe ?
Ressources utilisées dans cette partie :
Obtenir des tokens d'accès et de rafraîchissement
Pour récupérer le access_token qui devra être inclus dans les en-têtes de chaque requête envoyée à l'API, une route spécifique existe :
Cette route nécessitera un corps spécifique pour retourner ce qui est nécessaire pour identifier vos autres requêtes (le access_token).
Voici le corps de la requête :
Le client_id et le client_secret vous seront fournis par l'équipe d'Ermeo. Cela nous permettra de savoir que vous envoyez la requête depuis une source différente de notre plateforme et de notre application. Le nom d'utilisateur et le mot de passe sont vos identifiants habituels, les mêmes que ceux utilisés pour accéder à la plateforme et à l'application.
Enfin, le grant_type correspond au type d'authentification fourni dans le corps de la requête. Dans ce cas, comme vous essayez de vous connecter avec votre nom d'utilisateur et votre mot de passe, cela doit être défini sur password.
Si vous envoyez cette requête avec succès, l'API devrait renvoyer une réponse contenant le corps suivant :
Trois éléments sont importants dans cette réponse. Le access_token est le token généré qui sera utilisé pour authentifier toutes les autres requêtes. Ce token est valable pendant 2 heures à partir du moment où la requête d'authentification a été envoyée (7200 secondes, la valeur correspondant à la clé expires_in). Après cette période, vous devrez envoyer à nouveau une requête d'authentification.
Le refresh_token peut également être très utile. Il permet de générer un nouveau access_token sans demander à nouveau le nom d'utilisateur et le mot de passe.
3. Comment récupérer un access_token avec un refresh_token ?
Le refresh_token est un token valable pendant 2 semaines. Il permet de générer un nouveau access_token sans demander à nouveau le nom d'utilisateur et le mot de passe. Par conséquent, vous n'avez pas besoin de stocker ces informations confidentielles (ce qui est considéré comme une très mauvaise pratique et une faille de sécurité) car vous pouvez stocker ce refresh_token à la place. Voici comment l'utiliser pour demander un autre access_token lorsque celui-ci expire :
Comme vous pouvez le voir, la route est exactement la même que celle que nous avons utilisée dans la partie précédente. Cependant, le corps envoyé avec cette requête est un peu différent :
Le grant_type est maintenant défini sur refresh_token, indiquant à l'API que vous essayez maintenant de générer un nouveau access_token grâce à un refresh_token.
Au lieu de spécifier un nom d'utilisateur et un mot de passe, vous devez maintenant passer dans le corps le refresh_token que vous avez récupéré lors de votre authentification précédente. La réponse de l'API sera exactement la même que dans la partie précédente.
Cette réponse vous donnera un nouveau access_token, valable pendant 2 heures, et un nouveau refresh_token, valable pendant 2 semaines. Veuillez noter qu'un refresh_token ne peut être utilisé qu'une seule fois.
Envoyer votre première requête authentifiée
Rappel des ressources utilisées dans cette partie :
Obtenir des tokens d'accès et de rafraîchissement
Maintenant que vous avez tout ce dont vous avez besoin pour générer un access_token, voyons un exemple de comment vous pouvez l'utiliser pour envoyer votre première requête authentifiée. Dans cet exemple rapide, vous verrez comment récupérer la liste de tous les actifs de votre espace de travail.
Commençons par envoyer une requête pour générer un access_token afin d'authentifier notre requête Obtenir tous les actifs :