L'API (interface de programmation) BlueSecure permet à vos outils internes d'échanger directement avec votre espace BlueSecure : synchroniser vos utilisateurs et groupes, piloter vos campagnes de formation ou récupérer vos rapports et vos fuites de données, sans passer par l'interface. Cet article explique à quoi elle sert, comment elle fonctionne et comment la mettre en place.
Sommaire
Prérequis
- Avoir accès au menu Organization > Settings de votre plateforme BlueSecure.
- Disposer d'une personne ou d'un outil capable d'envoyer des requêtes HTTPS (développeur, intégrateur, outil d'automatisation).
- Savoir quelles données votre intégration doit lire ou modifier, afin de ne demander que les permissions nécessaires.
1 À quoi sert l'API BlueSecure ?
L'API vous permet d'automatiser des tâches que vous réalisez aujourd'hui à la main dans la plateforme, et de faire circuler vos données BlueSecure vers vos propres outils. Exemples d'usages :
- Tenir vos utilisateurs à jour automatiquement : ajouter ou mettre à jour vos collaborateurs en masse et aligner les membres d'un groupe sur une liste d'adresses e-mail issue de votre SIRH (système d'information RH) ou de votre annuaire.
- Piloter vos campagnes de formation : créer, modifier, dupliquer, supprimer ou changer le statut de vos campagnes Learning, et consulter leurs rapports.
- Construire vos propres contenus : créer ou dupliquer des cours dans le Learning Studio, et gérer leurs sections, chapitres, quiz, questions et médias.
- Exploiter vos indicateurs dans vos outils : récupérer les statistiques de votre organisation, vos rapports, vos campagnes de phishing et vos fuites de données (DataWatch™) pour les intégrer à vos tableaux de bord ou à vos outils de suivi.
| Domaine | Ce que vous pouvez faire |
|---|---|
| Organization | Consulter les informations de l'organisation et ses statistiques globales. |
| Users | Consulter, ajouter et mettre à jour vos utilisateurs. |
| Groups | Consulter vos groupes et tenir leurs membres à jour. |
| Learning Campaigns | Créer, piloter et suivre vos campagnes de formation. |
| Learning Studio | Créer et modifier vos propres contenus de formation. |
| Reports | Consulter vos campagnes de phishing et vos rapports. |
| Breaches | Consulter les fuites de données détectées (DataWatch™). |
ℹ️ Info
La synchronisation d'un groupe via l'API ne crée pas de nouveaux utilisateurs : ajoutez-les d'abord avec l'opération d'ajout en masse des utilisateurs, puis synchronisez le groupe.
2 Comment fonctionne l'authentification
L'API utilise le standard OAuth2 (protocole d'autorisation sécurisé), en mode « client credentials ». Le principe en trois temps :
- Vos identifiants : votre organisation dispose d'un Client ID (identifiant public) et d'un Client secret (mot de passe de l'intégration).
- Le jeton d'accès : votre intégration échange ces identifiants contre un jeton d'accès de courte durée, limité à votre organisation et aux permissions demandées.
- Les appels : chaque requête à l'API inclut ce jeton. Une fois le jeton expiré, votre intégration en redemande un nouveau.
⚠️ Alerte
Toutes les requêtes doivent être envoyées en HTTPS. Les jetons ne donnent accès qu'aux données de votre propre organisation.
3 Accéder aux paramètres API
Dans le menu de gauche, ouvrez Organization > Settings, puis dans la rubrique SECURITY, cliquez sur API. La page API settings regroupe :
- votre Client ID, avec un bouton pour le copier ;
- le champ Latest client secret (displayed once), qui affiche votre secret une seule fois après sa génération ;
- les boutons Rotate secret (générer un nouveau secret), Revoke client (révoquer les identifiants) et View API Docs (ouvrir la documentation technique) ;
- un exemple de requête pour obtenir un jeton d'accès, et la liste des permissions disponibles.
💡 Astuce
Le secret n'est affiché qu'une seule fois : copiez-le immédiatement et stockez-le dans un coffre-fort de mots de passe ou un gestionnaire de secrets, jamais dans un e-mail ou un fichier partagé.
4 Choisir les permissions (scopes)
Les permissions, appelées scopes, définissent ce que votre jeton a le droit de faire. Vous les indiquez au moment de demander le jeton, séparées par un espace. Demandez uniquement celles dont votre intégration a besoin.
| Permission | Ce qu'elle autorise |
|---|---|
organization:read |
Lire les informations de l'organisation, les utilisateurs, les groupes, les rapports, les fuites de données et les campagnes de phishing. |
organization:write |
Gérer les utilisateurs et les appartenances aux groupes. |
organization:learning:read |
Lire les campagnes de formation et leurs rapports. |
organization:learning:write |
Créer, modifier, dupliquer, supprimer et changer le statut des campagnes de formation. |
organization:studio:read |
Consulter les contenus du Learning Studio. |
organization:studio:write |
Créer et modifier des contenus dans le Learning Studio. |
⚠️ Alerte
Les opérations d'écriture demandent deux permissions combinées : organization:write + organization:learning:write pour les campagnes de formation, et organization:write + organization:studio:write pour le Learning Studio.
5 Obtenir un jeton d'accès et appeler l'API
5.1 Demander un jeton
Votre intégration envoie une demande de jeton au service d'authentification BlueSecure, avec quatre champs :
grant_type=client_credentialsclient_id: votre Client ID ;client_secret: votre Client secret ;scope: la ou les permissions souhaitées, par exempleorganization:read.
Un exemple de requête prêt à l'emploi, déjà rempli avec votre Client ID, est affiché sur la page API settings dans l'encadré How to obtain an access token. Il vous suffit d'y remplacer YOUR_CLIENT_SECRET par votre secret.
5.2 Appeler l'API avec le jeton
Ajoutez le jeton obtenu dans l'en-tête de chaque requête, sous la forme Authorization: Bearer VOTRE_JETON. Les adresses à appeler et le détail de chaque opération figurent dans la documentation technique.
5.3 Consulter la documentation technique
Cliquez sur View API Docs depuis la page API settings, ou ouvrez directement la documentation de l'API BlueSecure. Vous y trouverez, pour chaque opération, les paramètres attendus, des exemples de réponse et des exemples de code dans plusieurs langages (Shell, Ruby, Node.js, PHP, Python). La spécification OpenAPI (format standard de description d'API) est également téléchargeable pour l'importer dans vos outils.
6 Sécuriser et gérer vos identifiants
- Rotate secret : génère un nouveau secret. Utilisez-le si vous avez perdu votre secret, si vous pensez qu'il a été exposé, ou dans le cadre d'un renouvellement régulier. Pensez à mettre à jour toutes les intégrations qui utilisent l'ancien secret.
- Revoke client : révoque les identifiants de l'API. À utiliser si vous n'utilisez plus l'API ou en cas de compromission.
⚠️ Alerte
Générer un nouveau secret ou révoquer le client interrompt les intégrations qui utilisent les identifiants actuels. Prévenez les équipes concernées avant d'agir.
Questions fréquentes
J'ai perdu mon Client secret, comment le retrouver ?
Le secret n'est affiché qu'une seule fois et ne peut pas être consulté à nouveau. Générez-en un nouveau avec le bouton Rotate secret, puis mettez à jour vos intégrations.
Mon intégration peut-elle accéder aux données d'une autre organisation ?
Non. Les jetons d'accès sont limités à votre seule organisation.
Je n'arrive pas à créer ou modifier une campagne de formation via l'API. Pourquoi ?
Vérifiez que votre jeton a bien été demandé avec les deux permissions organization:write et organization:learning:write. Il en va de même pour le Learning Studio avec organization:write et organization:studio:write.
La synchronisation d'un groupe crée-t-elle les utilisateurs manquants ?
Non. Ajoutez d'abord les utilisateurs avec l'opération d'ajout en masse, puis synchronisez le groupe avec la liste d'e-mails.
Faut-il demander toutes les permissions pour être tranquille ?
Non. Demandez uniquement les permissions nécessaires à votre intégration : un outil qui lit vos rapports n'a pas besoin des droits d'écriture. Cela limite les conséquences en cas de fuite d'un jeton.