Jetons de l'API d'intégration

L’API d’intégration connecte les systèmes de votre organisation (RH, ERP, BI) à Eduvem : création de comptes et inscription automatiques, extraction de rapports, téléchargement de certificats et plus encore. Tout accès passe par des jetons créés par l’administrateur.

Créer et gérer les jetons

• Créez plusieurs jetons nommés et indépendants - un par système intégré est la bonne pratique. Chacun peut être révoqué sans affecter les autres.
• La valeur du jeton n’est affichée qu’une seule fois, à la création. Conservez-la dans le coffre-fort de secrets de votre organisation : en cas de perte, la solution consiste à supprimer le jeton et à en créer un autre.
• Certaines données exigent une permission supplémentaire accordée sur le jeton : le téléchargement de certificats, l’historique d’audit des inscriptions, les rapports et, dans les salles avec gestion des inscriptions, la décision sur les demandes (Inscriptions (écriture)). N’accordez que ce que l’intégration utilise réellement. Pour créer, modifier ou supprimer des participants via l’API, le jeton a besoin de Utilisateurs (écriture) ; pour créer ou modifier des salles, des versions de contenu, des groupes et des rôles, voir Écriture des salles, versions de contenu, groupes et rôles via l’API.
• Pour modifier les portées d’un jeton déjà créé, utilisez l’icône modifier les permissions dans la liste des jetons.
• Les webhooks sont liés au jeton qui les a configurés : supprimer le jeton, ou lui retirer la permission Rapports (lecture), arrête ses webhooks. Lors d’un remplacement de jeton, l’équipe d’intégration doit réactiver les webhooks avec le nouveau jeton avant que vous ne supprimiez l’ancien.

Modifier les autorisations d’un jeton

Les autorisations d’un jeton peuvent être modifiées après sa création, sans le remplacer : cliquez sur l’icône crayon (Modifier les autorisations) sur la ligne du jeton. La fenêtre s’ouvre avec les autorisations actuelles déjà cochées.

• Ajouter une autorisation demande une confirmation : le jeton étant déjà utilisé, l’intégration accède aux nouvelles données immédiatement, dès son prochain appel.
• Retirer une autorisation enregistre directement, sans confirmation.
• L’autorisation Plateforme est incluse dans tous les jetons et ne peut pas être décochée.
• Si un autre administrateur a modifié le même jeton pendant que la fenêtre était ouverte, la modification est refusée et la liste est actualisée : vérifiez et réessayez.

Ce que fait l’intégration

Création et mise à jour de participants (individuelle et en masse), gestion des groupes et des rôles, inscriptions et changements d’état (approuver, refuser, annuler, réactiver), liste et téléchargement des certificats en PDF, rapports (synthèse par salle et exportation par inscription), catalogue des salles et des contenus, et le classement.

Lors d’une inscription via l’API, le participant peut être identifié par e-mail ou CPF - s’il n’existe pas encore, le compte est créé automatiquement.

Écriture des participants par l’API

La permission Utilisateurs (écriture) permet au jeton de créer, modifier, changer le statut et supprimer des participants via l’API (POST /integrations/users, POST /integrations/users/multiple, PUT /integrations/users/{uuid}, PUT /integrations/users/{uuid}/status/{status} et DELETE /integrations/users/{uuid}). Elle est toujours disponible dans la liste des permissions, n’est jamais cochée par défaut et n’est pas incluse dans la permission Plateforme.

• Sans cette permission, ces appels reçoivent l’erreur 403 (insufficientScope). La consultation des participants ne change pas et reste disponible pour tout jeton.
• Les jetons qui écrivaient déjà des participants ont reçu la permission lors de la mise à jour de la plateforme. Tout autre jeton exige qu’un administrateur coche Utilisateurs (écriture) dans Modifier les autorisations.
• Inscrire une personne qui n’existe pas encore, via les points d’accès d’inscription de salle ou de groupe, exige aussi Utilisateurs (écriture), en plus de la permission de la salle ou du groupe.
• Modifier l’e-mail ou définir le mot de passe d’une personne qui a un rôle d’administrateur, d’éditeur, d’observateur ou de tuteur, via PUT /integrations/users/{uuid}, exige aussi Connexion des administrateurs et tuteurs. Voir Connexion des administrateurs et tuteurs.

Écriture des salles, versions de contenu, groupes et rôles via l’API

Quatre permissions contrôlent les appels d’écriture de ces domaines. Toutes sont toujours disponibles dans la liste des permissions, ne sont jamais cochées par défaut et ne sont pas incluses dans la permission Plateforme. Les consultations (GET) ne changent pas.

Permission	Ce qu’elle autorise
Salles (écriture)	Créer et modifier des salles (POST /integrations/courseClasses/create, PUT /integrations/courseClasses/{uuid}), inscrire des personnes dans une salle (POST /integrations/courseClasses), supprimer des inscriptions (DELETE /integrations/courseClasses) et changer le statut d’une inscription (PUT /integrations/enrollments/{uuid}/state/{state}).
Versions de contenu (écriture)	Créer et modifier des versions de contenu (POST /integrations/courseVersions/create, PUT /integrations/courseVersions/{uuid}) et créer une salle à partir d’une version (POST /integrations/courseVersions).
Groupes (écriture)	Créer, modifier et supprimer des groupes, ajouter ou retirer des personnes et lier ou dissocier des salles (tous les appels d’écriture de /integrations/teams).
Rôles (écriture)	Accorder et retirer des rôles (POST /integrations/roles et DELETE /integrations/roles/{uuid}), y compris les rôles d’administrateur. À n’accorder qu’à des systèmes en qui vous avez pleinement confiance. Accorder un rôle, quel qu’il soit, exige aussi Connexion des administrateurs et tuteurs.

• Sans la permission, l’appel reçoit l’erreur 403 (insufficientScope).
• Inscrire une personne qui n’existe pas encore, ou l’ajouter à un groupe, exige aussi Utilisateurs (écriture).
• L’authentification d’utilisateur (POST /integrations/auth/authenticationRequest) n’exige Salles (écriture) que lorsque l’appel utilise autoEnroll avec une salle indiquée, car c’est alors qu’elle inscrit quelqu’un. Sans autoEnroll, elle n’exige aucune permission d’écriture.
• Dans les salles avec gestion des inscriptions, changer le statut d’une inscription exige Salles (écriture) et aussi Inscriptions (écriture).
• Les jetons qui effectuaient déjà ces appels continuent de fonctionner après la mise à jour de la plateforme. Tout autre jeton exige qu’un administrateur coche la permission dans Modifier les autorisations.

Connexion des administrateurs et tuteurs

La permission Connexion des administrateurs et tuteurs protège les comptes de gestion. Sans elle, le jeton ne peut pas agir sur une personne qui a un rôle d’administrateur, d’éditeur, d’observateur ou de tuteur (administrateur de division compris). Elle est nécessaire pour :

• la connexion partenaire (POST /integrations/auth/authenticationRequest) d’une personne ayant l’un de ces rôles ;
• accorder un rôle, quel qu’il soit, via l’API (POST /integrations/roles) ;
• modifier l’e-mail ou définir le mot de passe d’une personne ayant l’un de ces rôles (PUT /integrations/users/{uuid}).

Les participants n’en ont pas besoin. Les administrateurs de la plateforme Eduvem sont toujours refusés, avec ou sans la permission. Sans elle, l’appel reçoit l’erreur 403 (insufficientScope).

• Les jetons qui existaient lors de la mise à jour de la plateforme ont reçu la permission automatiquement. Les nouveaux jetons commencent sans elle : un administrateur de l’institution la coche dans Modifier les autorisations.
• Lorsque vous la cochez, l’écran affiche l’avertissement : “Attention : permet à ce jeton de connecter des personnes en tant que vos administrateurs, éditeurs, observateurs et tuteurs par la connexion partenaire, sans leur mot de passe. À n’activer que pour une intégration d’authentification unique en qui vous avez pleinement confiance.” La confirmation d’ajout répète l’alerte : “Attention : avec la Connexion des administrateurs et tuteurs, cette intégration peut ouvrir des sessions en tant que vos administrateurs, éditeurs, observateurs et tuteurs sans leur mot de passe.”

Lien d’accès de la connexion partenaire

La connexion partenaire (POST /integrations/auth/authenticationRequest) renvoie une URL que votre système ouvre pour amener la personne sur la plateforme, déjà connectée et, lorsqu’une salle est indiquée, directement dans cette salle.

• L’URL contient un code à usage unique, valable 2 minutes. Ce n’est pas la session de la personne : la session n’est créée que lorsque la page s’ouvre et échange le code. Ensuite, l’adresse affichée dans le navigateur ne contient rien de sensible.
• Générez l’URL au moment du clic et ouvrez-la aussitôt. Ne conservez pas l’URL pour la réutiliser et ne l’envoyez pas par e-mail : un lien ouvert une deuxième fois, ou après 2 minutes, ne connecte pas.
• Dans ce cas, l’écran de connexion affiche : “Ce lien d’accès a expiré ou a déjà été utilisé. Retournez au système d’où vous venez et ouvrez à nouveau le contenu.” Il suffit de revenir au système d’origine et de cliquer à nouveau.
• Si une autre personne est déjà connectée sur le même navigateur, le lien bascule la session vers la personne du lien, comme auparavant.

Inscriptions gérées par l’API

La permission Inscriptions (écriture) permet au jeton de gérer les délégations d’approbateurs et d’approuver, refuser et annuler les inscriptions des salles avec gestion des inscriptions. Elle n’apparaît dans la liste des permissions que tant que l’institution a la gestion des inscriptions active (ou lorsque le jeton la possède déjà), n’est jamais cochée par défaut et n’est pas incluse dans la permission Plateforme.

La permission Synchronisation des personnes permet au jeton d’envoyer la liste complète des collaborateurs, de consulter les synchronisations et d’approuver ou d’annuler les synchronisations envoyées via l’API ; voir Synchronisation des personnes. Elle n’apparaît dans la liste des permissions que tant que la synchronisation des personnes est active dans l’institution (ou lorsque le jeton la possède déjà), n’est jamais cochée par défaut et n’est pas incluse dans la permission Plateforme. Les synchronisations qui déclenchent une limite de sécurité exigent toujours l’approbation d’une personne sur la plateforme.

Approuver, refuser et annuler une inscription

Utilisez le point d’accès d’état de l’inscription, avec l’identifiant de la personne qui décide. Le jeton a besoin de Salles (écriture) et aussi de Inscriptions (écriture) :

PUT /integrations/enrollments/{enrollmentUUID}/state/{state}?approverIdentifier=<nom d'utilisateur, e-mail ou CPF>

Dans une salle avec gestion des inscriptions :

• enrolled approuve une inscription demandée ; denied la refuse. Une salle pleine envoie la personne approuvée sur la liste d’attente au lieu de lui donner la place.
• cancelled annule une inscription déjà inscrite. Tout autre changement d’état est refusé avec invalidEnrollmentStateTransition (400).
• approverIdentifier est obligatoire et doit être une personne qui pourrait décider de cette demande : le gestionnaire du participant, un remplaçant de celui-ci, le gestionnaire du gestionnaire (par escalade) ou un administrateur de la salle. Personne n’approuve sa propre demande.
• Un refus fait par l’API enregistre le motif Autre ; il n’y a pas de champ de motif.
• En cas de succès, la réponse est 204, sans corps.
• Dans les salles sans gestion des inscriptions, le point d’accès fonctionne comme avant et ignore approverIdentifier.

Les erreurs les plus courantes :

Code	Erreur	Quand
403	insufficientScope	Le jeton n’a pas Inscriptions (écriture) ou Salles (écriture).
403	approverNotAuthorized	La personne indiquée ne peut pas décider de cette demande.
400	approverIdentifierRequired, approverNotFound	approverIdentifier est absent ou la personne n’existe pas dans l’institution.
404	enrollmentNotFound	L’inscription n’existe pas.
409	requestsClosed	Le délai de la salle est passé ; l’inscription est clôturée.
409	enrollmentStateChangedConcurrently	Quelqu’un a modifié l’inscription avant.
409	selfApprovalNotAllowed	L’approbateur est le demandeur lui-même.

Position sur la liste d’attente

Les lectures d’inscription (GET /integrations/enrollments/{enrollmentUUID} et la liste) comportent le champ enrollmentQueuePosition : un nombre entier, où 1 est le prochain à être inscrit. Il n’est renseigné que tant que l’inscription est sur la liste d’attente d’une salle gérée ; sinon il est vide.

Remplaçants de gestionnaires

Les systèmes RH peuvent enregistrer qui remplace un gestionnaire pendant une période :

• POST /integrations/managerDelegates, avec principalIdentifier (le gestionnaire), delegateIdentifier (le remplaçant), validFrom et validUntil au format ISO-8601 avec fuseau horaire (par exemple, 2026-10-07T12:00:00Z). Les personnes sont identifiées par nom d’utilisateur, e-mail ou CPF. Il répond 201 avec la délégation créée, avec source égal à integration.
• GET /integrations/managerDelegates?principalIdentifier=<gestionnaire> liste uniquement les délégations créées par l’intégration.
• DELETE /integrations/managerDelegates/{delegationUUID} révoque une délégation (204, même si elle était déjà révoquée).

La période doit commencer avant de se terminer, se terminer dans le futur et durer au plus 366 jours ; le remplaçant doit être une personne active, différente du gestionnaire. Ces appels répondent 403 (insufficientScope) sans la permission, ou (enrollmentManagementDisabled) si la ligne hiérarchique ou la gestion des inscriptions est désactivée pour l’institution, et sont limités à 60 appels par minute.

Audit

Chaque appel effectué via l’API est enregistré par la plateforme (quoi, quand et avec quel jeton). Cet enregistrement n’est pas affiché dans le panneau d’administration : si vous devez savoir ce qu’un système externe a fait, demandez la consultation au support Eduvem en indiquant le jeton et la période.

Limites d’utilisation

• Le trafic est limité par institution (budget par défaut de 1 000 requêtes par minute, ajustable sur demande).
• Les opérations lourdes (exportations d’audit/de rapports et téléchargement de certificats) disposent d’un budget propre, plus faible - un pic sur celles-ci ne bloque pas le reste de l’intégration.
• Les listes sont paginées (100 éléments par page par défaut, 1 000 au maximum) : demandez aux intégrateurs de toujours paginer.
• La liste des certificats a une limite plus basse : 100 éléments par page au maximum (une page plus grande est refusée).
• Chaque serveur accepte au maximum 2 appels simultanés par jeton et 4 par institution. Un appel au-delà reçoit l’erreur 429 (integrationConcurrencyExceeded) avec l’en-tête Retry-After: 5 : attendez et réessayez. Les intégrations qui font un appel à la fois ne sont jamais concernées.
• Pour garder un système externe synchronisé, ne téléchargez pas toutes les inscriptions à chaque exécution : après le premier chargement, envoyez lastModified avec l’heure de début de la synchronisation précédente et mettez à jour les enregistrements par identifiant d’inscription. Arrêtez la pagination lorsqu’une page renvoie moins d’éléments que la taille demandée.
• Dans la liste des inscriptions par numéro de page, les totaux (count et pageCount) sont calculés une fois par combinaison de filtres sur chaque serveur et réutilisés jusqu’à 10 minutes : ils peuvent ne pas refléter les inscriptions créées ou modifiées entre-temps. C’est pourquoi le critère d’arrêt est une page incomplète, et non pageCount.
• Une requête trop lourde qui dépasse le temps limite de la base de données reçoit l’erreur 503 (queryTimeout) avec l’en-tête Retry-After: 60 : attendez une minute et réessayez, de préférence avec des filtres plus étroits ou avec la pagination par curseur décrite dans la documentation de l’API.

Astuce

Traitez les jetons comme des mots de passe : jamais dans des feuilles de calcul ou des e-mails, toujours un par système, et révoquez immédiatement les jetons des intégrations désactivées.

Voir aussi

• Documentation de l’API