Si vous utilisez l’API v2, sachez que le type d’authentification JSON Web Token (JWT) n’est pas compatible.
Un grand nombre de fonctionnalités d’Iterop est accessible via une API REST pour une intégration efficace avec vos outils. Cette interface est protégée par un mécanisme de sécurité avancé qui empêche tout accès non souhaité.
Pour cela, nous utilisons un système de clés uniques (équivalent d’identifiant/mot de passe) qui permettent une authentification indépendante des utilisateurs courants. La gestion de ces identifiants se fait par une interface dédiée.
Deux mécanismes de sécurité sont disponibles :
- L’envoi d’identifiants par HttpBasic (base64), implémenté par la quasi-totalité des clients. Cette méthode est la plus simple mais n’est pas adaptée aux fortes charges car la vérification du mot de passe est volontairement lente pour renforcer la sécurité.
- L’utilisation d’un token JWT. Ce token, à durée limitée, peut être généré à l’aide des identifiants avec une requête POST sur
/api/auth/jwt. Cette méthode est plus efficace (le mot de passe n’est vérifié qu’à la demande du token) mais n’est malheureusement pas toujours prise en compte nativement par les clients. Il est alors nécessaire de gérer à la main la génération du token lorsque le précédent n’est plus valide.
Créer un accès REST
Voici la démarche pour créer un nouveau couple clé d’accès/clé secrète :
- Allez dans l’onglet Administration
- Allez dans l’encart Accès REST
- Remplissez le nom du nouvel accès ainsi que le type de droit dans les champs texte correspondant puis cliquez sur le bouton
- Une clé d’accès ainsi qu’une clé secrète seront automatiquement générées
Pensez à noter les identifiants 1️⃣ qui ne seront plus visibles par la suite (seule la clé d’accès sera accessible). A tout moment, il vous est possible de supprimer cet accès 2️⃣ ou de régénérer la clé secrète 3️⃣ ce qui aura pour effet d’invalider celle faite précédemment.
Utiliser les méthodes de l’API avec l’interface Iterop
La documentation concernant l’utilisation de l’API REST est disponible à tout moment à travers le lien “?”. Cette documentation décrit chaque opération accessible depuis l’extérieur avec une description des données attendues et fournies
Cette interface permet de tester avant toute intégration les différentes méthodes utilisables. Pour cela, il suffit de cliquer sur la gestion de l’autorisation . Cela ouvre la fenêtre suivante :
En fonction du choix de la méthode d’authentification, il faut remplir la partie correspondante. Dans le cas du HttpBasic (1), il faut indiquer respectivement la clé d’accès et la clé secrète dans les champs username et password. Si vous souhaitez utiliser du JWT, il faut préalablement générer un token en utilisant la méthode de génération associée (présent dans la même interface dans la catégorie auth) et insérer dans l’interface précédente “Bearer <<token>>“, où <<token>> est à remplacer par ce que vous a fourni l’appel précédent.
Nous fournissons aussi sur demande un client Java complet afin de faciliter l’intégration.
Utiliser un logiciel tiers pour utiliser les méthodes de l’API
Pour cet exemple, nous utiliserons l’application « Insomnia » qui est un client REST.
- Créez une nouvelle requête
- Donnez un nom à la requête, indiquez son type (POST pour cet exemple) ainsi que le type de Body (JSON)
- Choisir un moyen d’authentification
- Renseignez le couple « login – mot de passe » généré plus tôt.
- Renseignez l’url de la requête basée sur « https://votre-instance.iterop.cloud/api/requete »
- Renseignez le corps de la requête dans l’onglet « JSON » (« Body » si le type n’est pas renseigné) et cliquer sur « Send »
1: Bouton « Send »
2 : Code de retour de la requête (voir les différents codes et leur signification)
3 : Corps de la requête
4 : Réponse éventuelle de la requête (notamment pour les méthodes GET)
