Clés API

Une clé API permet à un autre système de votre entreprise —un ERP, un tableau de bord, un script— de lire ou d’écrire dans goPrevina via l’API REST, sans utiliser le compte de quiconque. Tous les appels passent par le chemin de base /api/v1.

1. Ce qui figure à l’écran

En haut, le bloc « Créer une clé » avec le champ « Nom », les « Portées » (« Lecture », « Écriture », « Analyses (webhook FHIR) » et « Prestataire de santé au travail (envoi seul) »), le sélecteur « Portée » et le bouton « Créer une clé ». En dessous, la liste déroulante « Droits par ressource (API publique) » la liste des clés de l’entreprise (s’il n’y en a aucune, le message « Aucune clé API pour l'instant. » s’affiche) et, tout en bas, « Envois des prestataires ».

Dès qu’il y a au moins une clé, quatre cartes d’état avec leur nombre apparaissent au-dessus de la liste : “Expirées”, “Expirent dans 30 jours”, “Révoquées” et “Actives”. Cliquez sur une carte pour ne voir que ces clés ; cliquez de nouveau pour les voir toutes.

2. Créer une clé

1. Saisissez un « Nom » qui indique qui l’utilise (par exemple « ERP de paie » ou « tableau de bord de direction »).

2. Cochez les « Portées » : « Lecture » si le système ne fait que lire des données ; ajoutez « Écriture » seulement s’il doit créer ou modifier des enregistrements. Ne cochez « Analyses (webhook FHIR) » que pour un laboratoire qui envoie des résultats en FHIR. « Prestataire de santé au travail (envoi seul) » est pour la clé d’un prestataire de santé au travail ou de dépistage d’Irlande ou du Royaume-Uni : elle remplace les autres portées et la portée reste « Cette entreprise ». Avec elle, le prestataire envoie à votre entreprise des rendez-vous, des résultats d’aptitude, des certificats et des résultats de dépistage (JSON, FHIR R4 ou CSV d’audiomètre et de spiromètre) et ne relit que les totaux de ses propres envois, rien d’autre.

3. Dans « Portée », choisissez « Cette entreprise », « Toutes les entreprises du groupe » (seulement un propriétaire ou un administrateur du compte) ou « Tous les clients du SPA » (seulement un administrateur du SPA).

4. Si la clé ne doit toucher que certaines données, ouvrez « Droits par ressource (API publique) » et cochez lecture ou écriture pour chaque ressource. « Lecture » et « Écriture » ne couvrent ni l’aptitude médicale ni le journal d’audit : chacun demande son propre droit.

5. Cliquez sur « Créer une clé ». Le message “Copiez cette clé maintenant — elle ne sera plus affichée :” apparaît. Copiez-la, stockez-la dans le système qui l’utilisera et cliquez sur “Terminé”.

3. Renouveler, révoquer et surveiller l’usage

Chaque clé de la liste indique son nom, ses portées, sa portée si ce n’est pas l’entreprise, et sa “dernière utilisation”. “Renouveler” génère une nouvelle valeur pour la même clé (l’ancienne cesse de fonctionner) et l’affiche une seule fois. “Révoquer” ouvre la confirmation “Révoquer la clé API” : une fois acceptée, la clé cesse de fonctionner immédiatement et c’est irréversible. Utilisez-le quand un système n’en a plus besoin ou si vous soupçonnez une fuite.

Une clé révoquée ou expirée est marquée “révoquée” ou “expirée” et n’a plus de boutons. La consommation de l’API par rapport au quota de votre offre se voit dans “Supervision des intégrations”.

« Envois des prestataires » liste ce que chaque clé de prestataire a envoyé : le prestataire (le nom de la clé), le type (rendez-vous, résultats d’aptitude, certificats, résultats de dépistage, FHIR, CSV d’audiomètre ou de spiromètre), les envois “Acceptés”, “Répétés” et “Rejetés” et la date de réception. Il ne montre que des totaux, jamais de données cliniques.

4. Une clé par système

Créez une clé distincte pour chaque système connecté : si l’un est retiré ou compromis, vous ne révoquez que la sienne, les autres continuent de fonctionner, et la “dernière utilisation” indique laquelle est active. La carte “Expirent dans 30 jours” signale les clés à renouveler à temps.

La clé donne accès aux données de l’entreprise avec les portées que vous avez choisies : conservez-la dans le gestionnaire de secrets du système qui l’utilise, jamais dans un e-mail ni dans un tableur.