Une clé d'API donne à un programme de votre entreprise, par exemple un script ou un entrepôt de données, un accès en lecture à vos données Odana. L'API est l'adresse que ce programme interroge à la place d'une personne. Vous créez la clé dans « Paramètres », onglet « Intégrations ».
L'onglet « Intégrations » apparaît pour les rôles qui ont le droit « Créer un jeton d'API » : l'« Administrateur principal » et l'« Administrateur » l'ont. Activer l'API et créer une clé demandent l'offre « Avancé » ou une offre supérieure.
Odana ouvre l'API à la demande de votre organisation, pour la sécurité de vos données. Tant que l'accès n'est pas ouvert, l'interrupteur « API » reste grisé.
Activer l'API et créer une clé
Étape 1 sur 8
Cliquez « Paramètres », la roue dentée en haut à droite, puis l'onglet « Intégrations ».
Étape 2 sur 8
Si le bouton « Demander l'ouverture » s'affiche à côté de l'interrupteur « API », cliquez-le. Votre messagerie ouvre un e-mail adressé à Odana, avec l'objet « Demande d'ouverture de l'API ». Envoyez-le. Une fois l'accès ouvert par Odana, l'interrupteur devient actif au rechargement de la page.
Étape 3 sur 8
Sous « Activation », activez l'interrupteur « API ».
Étape 4 sur 8
Sous « Clés d'API », cliquez « Créer une clé ». La fenêtre « Créer une clé d'API » s'ouvre.
Étape 5 sur 8
Remplissez « Nom de la clé », par exemple avec le nom du programme qui s'en servira. Sous « Droits », cochez ce que la clé pourra lire.
Étape 6 sur 8
Dans « Périmètre », choisissez les unités de travail (équipes, services ou sites) que la clé couvre. Sans sélection, la clé couvre toute l'entreprise. Dans « Expiration », choisissez 30, 90 ou 365 jours.
Étape 7 sur 8
Cliquez « Créer la clé ». La fenêtre « Clé créée » affiche la clé. Copiez-la avec l'icône de copie, puis enregistrez-la là où votre programme garde ses secrets.
Étape 8 sur 8
Cliquez « Terminer ». Le tableau affiche la clé avec son nom, ses quatre derniers caractères, ses droits, son périmètre, sa date d'expiration et l'état « Active ».
Le programme envoie la clé dans l'en-tête x-api-key de chaque demande, à une adresse qui commence
par https://<votre adresse Odana>/api/v1/. Votre adresse Odana est celle de la barre d'adresse
quand vous êtes connecté. Par exemple, GET https://<votre adresse Odana>/api/v1/campaign-runs
liste vos campagnes. La description complète des adresses, des paramètres et des réponses est
publiée au format OpenAPI, à https://<votre adresse Odana>/api/v1/openapi.json. La plupart des
outils d'intégration savent la lire.
Avec l'API, un programme lit vos données sans rien créer, modifier ni supprimer. Il envoie au plus 120 demandes par minute avec une même clé. Au-delà, l'API répond 429 et le programme doit attendre.
Les données que l'API sert
Une clé lit ce que ses droits couvrent, dans son périmètre :
- la liste de vos campagnes et leur état ;
- pour une campagne « Clôturée » dont les indicateurs sont calculés : le nombre total de réponses, les résultats agrégés, les tendances, les résultats par cible et l'explication d'un indicateur ;
- les plans d'action et leurs actions, avec leurs titres et descriptions tels que vos collègues les ont écrits ;
- la synthèse du pilotage ;
- les versions publiées du programme annuel de prévention (PAPRIPACT) ;
- les lignes des volets RPS du DUERP finalisés ;
- le journal d'audit, pour une clé qui couvre toute l'entreprise et porte le droit « Exporter le journal d'audit ».
Les résultats respectent le nombre minimum de réponses, comme à l'écran. L'API ne sert aucune donnée au niveau du répondant, aucun commentaire de répondant, aucun découpage par critère de profil (âge, ancienneté, catégorie) et rien du module Signalement. Les listes et les totaux des plans d'action ne comptent pas les actions issues d'un signalement.
Les résultats d'une campagne sont publiés une seule fois, quand elle est clôturée et que ses indicateurs sont calculés. Si vous cliquez « Reprendre » ou « Recalculer les indicateurs » après cette publication, ses résultats ne sortent plus par l'API, même après une nouvelle clôture. Son nom, son état et le nombre total de réponses publié restent lisibles. Une campagne comparée à une campagne de référence ne sort par l'API que si cette campagne de référence est publiée elle aussi.
Révoquer une clé ou suspendre l'API
Pour révoquer une clé, cliquez « Révoquer » sur sa ligne, puis « Révoquer la clé ». La clé cesse de fonctionner tout de suite et passe à « Révoquée ». Ce geste demande le droit « Révoquer un jeton d'API ».
Désactiver l'interrupteur « API » suspend toutes les clés sans les supprimer, et elles passent à « Suspendue ». Si vous le réactivez avant leur date d'expiration, elles reprennent. Une clé arrivée à expiration passe à « Expirée » et ne se prolonge pas : créez-en une nouvelle. Si votre entreprise passe à une offre sans l'API, les clés cessent de fonctionner mais restent listées et révocables.
Chaque demande faite avec une clé ajoute une ligne au journal d'audit. Voir Lire le journal d'audit.
Si ça ne se passe pas comme prévu
- L'interrupteur « API » est grisé et le bouton « Voir les offres » s'affiche à côté. Votre offre ne comprend pas l'API. Voir Voir son offre et en changer.
- Une demande répond 401. La clé manque, est mal copiée, révoquée ou expirée. Lisez son état dans le tableau des clés, puis créez-en une nouvelle si elle n'est plus « Active ».
- Une demande répond 403 avec le code
api_disabled. L'interrupteur « API » est désactivé. Réactivez-le, comme à l'étape 3. - L'interrupteur « API » est grisé et le bouton « Demander l'ouverture » s'affiche à côté. Odana n'a pas encore ouvert l'API à votre organisation. Demandez l'ouverture comme à l'étape 2.
- Toutes les demandes répondent 404, sauf
openapi.json. L'API n'est pas ouverte à votre organisation. Demandez l'ouverture comme à l'étape 2. - Une campagne « Clôturée » répond 409 avec le code
run_not_released. Si ses résultats ne sont jamais sortis par l'API, cliquez « Recalculer les indicateurs » sur la page de la campagne, puis relancez la demande une fois le calcul fini. Une campagne publiée, puis reprise ou recalculée, garde cette réponse.