Un jeton API permet à un logiciel tiers (paie, annuaire, planning, entrepôt de données) de lire ou d’écrire vos données Illizeo par l’API publique, dans les droits que vous lui accordez. Cet article explique comment créer un jeton, le transmettre, le modifier, le régénérer, le suspendre et le révoquer. Il s’adresse aux administrateurs de l’espace.
Avant de commencer #
- L’écran se trouve dans Paramètres › Gérer Illizeo › Jetons API. L’entrée n’apparaît que si votre abonnement comprend l’accès à l’API (il est ouvert pendant la période d’essai) et si l’un de vos rôles porte le droit « Voir les tokens API ».
- Créer, modifier, régénérer, désactiver ou révoquer un jeton demande en plus le droit « Créer / éditer / révoquer un token » au palier Exécuter. Sans lui, la liste et les fiches se lisent, mais aucun bouton d’action n’apparaît.
- Par défaut, seul le rôle Administrateur porte ces deux droits. Ils se règlent dans Paramètres › Gérer les employés › Rôles des employés (voir Permissions & rôles).
Un jeton agit au nom de son créateur #
Un jeton n’a pas de droits à lui : il hérite des droits et du périmètre de la personne qui l’a créé, jamais plus. Un appel qui lit les collaborateurs ne voit que ceux que cette personne voit dans l’application ; une écriture exige le même droit que le geste équivalent à l’écran. Les droits cochés sur le jeton viennent en plus : ils limitent ce que le jeton peut appeler.
- Si les droits du créateur changent, ceux du jeton changent avec eux, dès l’appel suivant.
- Si le compte du créateur n’est plus actif (départ, suspension), le jeton cesse de fonctionner.
- Un autre administrateur peut modifier ou régénérer le jeton : celui-ci continue d’agir au nom de son créateur.
Créez donc chaque jeton avec un compte dont les droits correspondent à ce que l’intégration doit voir.
La liste des jetons #
La page affiche d’abord la carte Plateforme API, qui résume la consommation de la période (voir Suivre l’utilisation d’un jeton et le dépanner), puis le tableau des jetons :
- Nom, avec la date de création et son auteur ;
- Jeton : le début de la valeur seulement, suivi d’astérisques ;
- Droits : les trois premiers, les autres au survol de la pastille « +n » ; les droits d’écriture sont colorés ;
- Créé par, Dernière utilisation (avec la date d’expiration), Statut et Actions.
Le champ Rechercher filtre par nom. Le bouton Documentation ouvre la documentation de l’API, décrite dans API publique : le guide du développeur.
Créer un jeton #
- Cliquez sur Nouveau jeton (ou Créer le premier jeton si la liste est vide).
- Nom (obligatoire, 100 caractères au plus) : nommez le système qui utilisera le jeton, par exemple « Synchronisation paie ». Vous le reconnaîtrez ainsi dans le journal d’utilisation. Deux jetons non révoqués ne peuvent pas porter le même nom ; l’écran le signale pendant la saisie.
- Expiration (optionnelle) : choisissez une date ; le jeton cesse de fonctionner à la fin de ce jour. Laissé vide, il n’expire jamais.
- Limite de débit (requêtes / minute) : de 1 à 10 000. Laissé vide, le jeton reçoit la limite par défaut indiquée sous le champ (60 requêtes par minute).
- Droits (au moins un) : cochez, ressource par ressource, Lire et/ou Écrire.
- Cliquez sur Créer le jeton.
Les ressources sont rangées en deux groupes, Données et Référentiel. Dans chaque groupe, Tout en lecture coche toutes les lectures et Effacer décoche tout le groupe. Seules les ressources des modules activés dans votre espace sont proposées : Planification, Annualisation, Budget, BDESE, Paie suisse ou Flex Office n’apparaissent que si le module l’est. Ce que chaque droit ouvre est détaillé dans le guide du développeur.
Copier le jeton, une seule fois #
Une fois le jeton créé, la fenêtre Votre jeton API affiche sa valeur complète (elle commence par illz_) et un exemple d’appel. Copiez la valeur avec le bouton de copie, transmettez-la par un canal sûr à la personne qui configure l’intégration, puis cliquez sur Je l’ai enregistré.
Cette valeur n’est plus jamais affichée : Illizeo n’en garde qu’une empreinte. Si elle est perdue, régénérez le jeton.
Modifier un jeton #
L’icône Modifier de la liste, ou le bouton Modifier de la fiche, ouvre la page Modifier le jeton API. Vous pouvez y changer le nom, l’expiration, la limite de débit et les droits, puis cliquer sur Enregistrer. Les changements valent dès l’appel suivant ; la valeur du jeton, elle, ne change pas.
Régénérer un jeton #
Le bouton Régénérer le jeton, sur la fiche ou sur la page de modification, demande une confirmation puis émet une nouvelle valeur. L’ancienne cesse de fonctionner immédiatement ; les droits, l’expiration et la limite de débit sont conservés. La nouvelle valeur s’affiche une seule fois, dans la fenêtre Votre nouveau jeton : mettez l’intégration à jour aussitôt.
Désactiver ou révoquer #
- Désactiver : l’interrupteur de la colonne Statut suspend le jeton, dont les appels sont alors refusés. Rebasculez-le pour le réactiver. C’est le bon geste pour couper une intégration le temps d’une vérification.
- Révoquer : l’icône Révoquer ouvre la confirmation Révoquer le jeton API. La révocation est définitive : toute intégration qui utilise le jeton perd l’accès immédiatement. Le jeton reste dans la liste avec le statut Révoqué, pour l’historique ; il ne peut plus être modifié, régénéré ni réactivé. Son nom redevient disponible pour un nouveau jeton.
À savoir #
- Un jeton dont la date d’expiration est passée affiche le statut Expiré et ses appels sont refusés ; chaque nuit, Illizeo le passe aussi en inactif. Pour le remettre en service, modifiez-le avec une nouvelle date d’expiration (ou sans date), enregistrez, puis réactivez-le dans la liste s’il apparaît inactif.
- Les créations, modifications, activations et désactivations à la main, régénérations et révocations de jetons sont tracées dans Paramètres › Gérer Illizeo › Logs utilisateurs. La valeur d’un jeton n’y figure jamais, seulement le fait qu’elle a changé.
- Un lien venu de la page d’intégrations d’un module peut ouvrir ce formulaire avec un nom et des droits déjà proposés. Rien n’est créé tant que vous ne cliquez pas sur Créer le jeton.
- Si votre abonnement ne comprend pas l’accès à l’API, la page l’indique et propose Voir les forfaits.
Questions fréquentes #
Je ne vois pas le bouton « Nouveau jeton ». #
Il demande le droit « Créer / éditer / révoquer un token » au palier Exécuter.
J’ai perdu la valeur d’un jeton. #
Elle ne peut pas être réaffichée. Régénérez le jeton et transmettez la nouvelle valeur à l’intégration.
Faut-il un jeton par intégration ? #
C’est préférable : chaque jeton a son nom, ses droits, sa limite et son journal d’utilisation, et se révoque sans couper les autres intégrations.
