Objectif
Cyber Guru offre la possibilité d’obtenir les taux de complétion des modules de formation pour chaque utilisateur de votre organisation via une API REST qui renvoie les données au format JSON, prêtes à être intégrées dans des systèmes de reporting externes.
Pour chaque utilisateur, l’API fournit le nombre de modules attribués et complétés, le pourcentage global de complétion ainsi que le détail par service (Awareness et Channel).
Ce guide contient les instructions et paramètres nécessaires pour appeler le service.
Périmètre
Les informations s’appliquent à la plateforme de Cyber Security Awareness Cyber Guru 2.0.
Prérequis
- Le client doit disposer des ressources techniques nécessaires pour appeler une API REST.
Procédure
Cyber Guru met à disposition deux API REST :
Obtenir un token :
URL : https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
Cette API permet d’obtenir un jeton d’autorisation. Paramètres d’appel (méthode POST) :
- client_id : ext-api
- client_secret : (fourni par Cyber Guru)
- grant_type : client_credentials
Obtenir la progression des utilisateurs :
URL : https://<host>/ext/report/users-progress-completion
Permet d’obtenir le détail de la progression de formation pour chaque utilisateur de l’entreprise. Pour appeler l’API, il est nécessaire de fournir le token obtenu précédemment comme Bearer token.
L’API accepte les paramètres suivants (méthode GET) :
| Paramètre | Type | Obligatoire | Description |
| team | chaîne | Non | Filtre les résultats pour une équipe spécifique |
| limit | entier | Non | Nombre maximum de résultats par page (min : 1, max : 1000) |
| page | entier | Non | Page de résultats à récupérer (par défaut : 1) |
Structure de la réponse
Chaque enregistrement utilisateur dans la réponse contient les champs suivants :
| Champ | Description |
| Adresse email de l’utilisateur | |
| assigned_total | Nombre total de modules attribués sur tous les services |
| completed_total | Nombre total de modules complétés sur tous les services |
| completion_rate_total | Pourcentage global de complétion (0–100), arrondi à 2 décimales |
| services.awareness | Détail des modules attribués, complétés et pourcentage pour le service Awareness |
| services.channel | Détail des modules attribués, complétés et pourcentage pour le service Channel |
Le pourcentage de complétion est de 0 lorsqu’aucun module n’a encore été attribué pour ce service.
Exemples de réponse
Réponse de base (sans pagination) :
{
"users": [
{
"email": "anna.ferrari@company.com",
"assigned_total": 20, "completed_total": 17, "completion_rate_total": 85.00,
"services": {
"awareness": { "assigned": 12, "completed": 11, "completion_rate": 91.67 },
"channel": { "assigned": 8, "completed": 6, "completion_rate": 75.00 }
}
},
{
"email": "marco.rossi@company.com",
"assigned_total": 20, "completed_total": 20, "completion_rate_total": 100.00,
"services": {
"awareness": { "assigned": 12, "completed": 12, "completion_rate": 100.00 },
"channel": { "assigned": 8, "completed": 8, "completion_rate": 100.00 }
}
}
],
"total_users": 2
}
Réponse avec pagination :
{
"users": [ { "email": "anna.ferrari@company.com", ... } ],
"total_users": 230,
"pagination": {
"current_page": 1, "per_page": 10, "total_items": 230, "total_pages": 23,
"from": 1, "to": 10, "has_next": true, "has_prev": false,
"next_page": 2, "prev_page": null, "first_page": 1, "last_page": 23
}
}
Les champs de l’objet pagination ont la même signification que pour les autres services de reporting.
Erreurs
| Code HTTP | Code erreur | Description |
| 400 | EXT_1000 | Paramètre d’entrée non valide (le message indique le paramètre concerné et les valeurs autorisées) |
| 400 | EXT_1000 | La page demandée n’existe pas (le message indique le nombre total de pages disponibles) |
| 404 | EXT_1003 | Erreur lors de la récupération des données |
| 422 | EXT_1004 | L’équipe indiquée n’existe pas dans l’entreprise |
| 500 | EXT_1001 | Token expiré ou non valide |
Notes techniques
- Pour les jeux de données comportant de nombreux utilisateurs, il est conseillé d’utiliser systématiquement les paramètres limit et page afin d’éviter les timeout. La valeur de limit doit être choisie en fonction de la taille de la population d’utilisateurs enregistrée sur la plateforme.
- Les données renvoyées excluent automatiquement les utilisateurs supprimés, suspendus ou sans licence active, ainsi que les utilisateurs à qui aucun module n’a encore été attribué.
Cyber Guru reste à disposition pour accompagner le client lors de la configuration et des tests sur l’environnement de staging et, après validation, sur l’environnement de production.