SoSafe API

Introduction

Que fait le SoSafe API ?

Le SoSafe API permet aux clients et partenaires comme vous d'accéder directement dans vos logiciels à des informations importantes sur vos mesures de cybersécurité SoSafe, sans avoir à vous connecter au manager pour consulter ou télécharger ces informations manuellement. Grâce à cet API, vous pouvez récupérer automatiquement des informations telles que, sans s'y limiter :

• Informations sur les employés : Qui sont les Utilisateurs inscrits à vos mesures de sensibilisation SoSafe ?
• Progression des formations des employés : Où en sont vos employés dans leur formation en cybersécurité ?
• Achèvement des leçons : Qui a terminé ses leçons et qui en a encore à compléter ?
• Engagement des équipes : Obtenez des informations sur le degré d'implication des différents groupes dans la formation.
• Niveaux de risque et comportement sécurisé : Dans quelle mesure les employés repèrent-ils les e-mails de phishing simulés et à quelle fréquence les signalent-ils ?

Vous pouvez utiliser ces informations pour suivre la progression des Utilisateurs, créer des rapports ou vous assurer que tout le monde suit la formation requise. Cela facilitera l'adoption de comportements sécurisés.

Pourquoi est-ce important pour nos clients et partenaires ?

L'API publique enrichit les offres actuelles de SoSafe en fournissant un accès automatisé et transparent aux données de formation en cybersécurité pour les clients et les partenaires. Bien que le manager et les fonctionnalités d'export de données de SoSafe aient été des outils fiables, l'API ouvre de nouvelles possibilités pour une gestion des données plus efficace et flexible, en permettant une intégration directe dans vos flux de travail.

Nombre de nos clients et partenaires ont exprimé leur souhait d'exploiter les données SoSafe à diverses fins au sein de leurs organisations, par exemple :

• Reporting : Automatiser le processus d'extraction des données de formation pour créer des rapports personnalisés adaptés à vos besoins spécifiques.
• Intégration dans les systèmes internes : Les organisations souhaitent souvent intégrer les données de formation SoSafe dans leurs systèmes de sécurité ou RH internes afin d'obtenir une vue complète de la formation des employés aux côtés d'autres indicateurs métiers.
• Création de tableaux de bord : Vous pouvez combiner nos données avec d'autres données auxquelles vous avez accès pour créer des tableaux de bord personnalisés permettant de visualiser la progression des formations et d'identifier les axes d'amélioration.

Pour les partenaires, cet API ouvre des possibilités supplémentaires :

• Intégration des données de formation SoSafe dans vos propres solutions : En tant que partenaire, vous pouvez créer des Intégrations qui incorporent les données de formation en cybersécurité dans vos propres produits ou services, en proposant des fonctionnalités à valeur ajoutée pour vos Clients.
• Solutions conjointes : Combinez les données de ​Formation en ligne de SoSafe avec d'autres outils ou services pour créer des solutions complètes de sécurité ou de formation pour vos clients.

Sans l'API, vous ne pouviez interagir avec l'interface SoSafe que manuellement pour collecter des données, ce qui limitait votre capacité à exploiter ces données de manière efficace.

Qu'est-ce qu'un API ?

Un API, qui signifie Application Programming Interface (interface de programmation applicative), est un outil permettant à deux systèmes ou programmes différents de communiquer entre eux et de partager des informations. Considérez-le comme un pont entre le logiciel de votre entreprise et SoSafe. Au lieu de vous connecter manuellement à SoSafe pour obtenir des données, l'API permet à votre système de les récupérer automatiquement lorsque vous en avez besoin, en lui donnant la capacité d'utiliser ces données exactement selon les besoins de votre organisation.

Limitations actuelles

Pour l'instant, l'API est limité aux données de ​Formation en ligne et de Simulation de phishing.

Documentation technique

L'API REST de SoSafe permet d'accéder aux données des Utilisateurs et de la formation en ligne depuis notre plateforme, facilitant ainsi l'intégration dans vos systèmes. Toutes les données sont renvoyées par défaut au format JSON, ce qui facilite leur traitement et leur personnalisation. En utilisant les API de SoSafe, vous acceptez nos Conditions d'utilisation.

Nos API utilisent des URL orientées ressources, des méthodes HTTP standard et des codes de réponse pour la gestion des erreurs. Ces API sont disponibles pour les clients Premium, avec une assistance fournie pour l'intégration et le dépannage.

Vous trouverez ci-dessous quelques informations de base. Pour la documentation technique complète, veuillez consulter la spécification OpenAPI.

Prérequis

Pour utiliser le SoSafe API, vous aurez besoin de :

• Une ​Formation en ligne SoSafe et / ou une Simulation de phishing en cours
• Un accès à la page de gestion des clés API du SoSafe Manager
  • Si vous n'avez pas accès à cette page, veuillez vérifier auprès de votre interlocuteur SoSafe si votre pack inclut l'utilisation des Intégrations d'Analyse des données
• Des connaissances techniques sur l'utilisation des API

URL de base

Assurez-vous d'utiliser l'URL de base correcte en fonction de l'emplacement de votre Compte lors des requêtes API. En général, il s'agit de https://connect.sosafe.de.

Authentification

Pour accéder à l'API de SoSafe, les Utilisateurs doivent s'authentifier via un processus en deux étapes impliquant une clé API et un jeton de session.

1. Générer une clé API : Obtenez votre clé API depuis le portail Manager. Cette clé est utilisée pour demander des jetons de session, mais pas pour accéder directement à l'API. Veillez à sélectionner les portées appropriées en fonction des requêtes API que vous souhaitez utiliser ultérieurement.
2. Connexion pour le JSON Web Token (JWT) : Envoyez une requête POST à /auth/login avec votre clé API dans l'en-tête X-Api-Key. Une requête valide renvoie un jeton de session JWT à courte durée de vie.
3. Effectuer des requêtes API : Incluez le JWT dans l'en-tête Authorization: Bearer <jwt> pour accéder à l'API.
4. Renouvellement du jeton : Une fois expiré, utilisez à nouveau la clé API pour obtenir un nouveau jeton de session JWT.

Pour des raisons de sécurité, les requêtes API doivent être effectuées via HTTPS. Les clés API compromises peuvent être révoquées depuis le portail.

Format de réponse

Les réponses de l'API de SoSafe sont formatées en JSON. Toutes les dates et heures dans les réponses suivent le standard UTC (Coordinated Universal Time), garantissant une cohérence entre les différents fuseaux horaires.

Point de terminaison Utilisateurs

Le point de terminaison Utilisateurs /users permet d'accéder à la liste des Utilisateurs associés à votre Compte, en renvoyant des informations pertinentes telles que le nom, l'e-mail, le niveau d'utilisateur, le groupe, les attributs personnalisés et le statut (activé/désactivé).

Exemples de cas d'utilisation :

• Obtenir la liste de tous les Utilisateurs

Récupérez la liste complète des Utilisateurs, y compris des attributs détaillés tels que leur nom, e-mail, niveau d'utilisateur, groupe et champs personnalisés.

• Obtenir la liste d'Utilisateurs spécifiques

Récupérez les données d'Utilisateurs spécifiques avec des options de filtrage supplémentaires :

Filtrer par groupe : Renvoyer les Utilisateurs appartenant à un groupe particulier.

Filtrer par campagne de formation : Renvoyer les Utilisateurs qui font partie d'une campagne de formation en ligne spécifique.

Points de terminaison ​Formation en ligne

Point de terminaison Campagnes

Le point de terminaison des Campagnes /campaigns/elearning permet d'accéder à la liste des Campagnes de formation en ligne actives sur votre Compte. Vous recevrez des informations telles que le nom et les dates d'une campagne, ainsi que son identifiant, ce qui peut être utile pour filtrer les données des autres points de terminaison.

Point de terminaison Analyse des données

Le point de terminaison ​Formation en ligne /analytics/elearning permet de récupérer la progression des Utilisateurs relative aux Modules de formation assignés et aux Campagnes. Une fois les données renvoyées, elles peuvent être filtrées pour en extraire les informations spécifiques requises.

Exemples de cas d'utilisation

• Obtenir la progression de la ​Formation en ligne pour tous les Utilisateurs

Récupérez les données de progression de tous les Utilisateurs pour l'ensemble du contenu de formation en ligne assigné.

• Obtenir la progression de la ​Formation en ligne d'un Utilisateur particulier

Récupérez la progression détaillée d'un Utilisateur spécifique.

• Obtenir la progression de la ​Formation en ligne d'un groupe d'Utilisateurs

Récupérez les données de progression d'un groupe d'Utilisateurs spécifié.

• Obtenir la progression de la ​Formation en ligne de toutes les Campagnes

Récupérez les rapports de progression de l'ensemble des Campagnes de formation en ligne.

• Obtenir la progression de la ​Formation en ligne d'une Campagne particulière

Récupérez la progression d'une campagne de formation en ligne spécifique.

• Obtenir la progression de la ​Formation en ligne d'un Module particulier

Récupérez la progression détaillée d'un Module de formation spécifique.

Points de terminaison Simulation de phishing

Campagnes

Le point de terminaison Simulation de phishing /phishing-simulation/campaigns permet de récupérer la liste des Simulations de phishing en cours et archivées (également appelées campagnes).

Les données renvoyées comprennent :

• L'identifiant de la campagne (qui peut être utilisé pour récupérer l'Analyse des données d'une campagne via le point de terminaison /phishing-simulation/analytics (voir ci-dessous))
• Le nom de la campagne
• La date de début et de fin de la campagne
• Le statut de la campagne : WAITING, ACTIVE, FINISHED, PAUSED, INACTIVE, PENDING, ALLOWLISTING_PENDING, SCHEDULED
• La version de la campagne
• Le statut d'archivage (true, false)
• La disponibilité de l'Analyse des données (true, false)

Veuillez consulter les spécifications OpenAPI pour un aperçu technique des données et du format correspondant.

Analyse des données

Le point de terminaison Simulation de phishing /phishing-simulation/analytics permet de récupérer des données détaillées sur la Simulation de phishing. Les données disponibles sont équivalentes à celles accessibles via Télécharger les données dans l'Analyse des données. Vous accédez ainsi à la liste de tous les e-mails de phishing simulés envoyés, avec les attributs suivants :

• Nom et identifiant du modèle
• Objet de l'e-mail
• Prénom et nom du destinataire
• Nom de l'expéditeur
• Langue
• Groupe d'utilisateurs
• Statut du message, incluant la date d'envoi
• Informations sur les interactions (dates d'ouverture, de clic, d'interaction, d'apprentissage, de réponse et de signalement, si disponibles)
• Indique si un agent utilisateur mobile a été utilisé
• Nom de l'instance et de la campagne

Vous pouvez utiliser ces données comme point de départ pour créer vos propres KPI, si vous le souhaitez, ou pour reproduire les KPI de SoSafe. Pour savoir comment ces derniers sont calculés, consultez la section Analyse des données de notre Knowledge Base.

Veuillez consulter les spécifications OpenAPI pour un aperçu technique des données et du format correspondant.

Codes de réponse/d'erreur

SoSafe utilise des codes de réponse HTTP standard pour indiquer le résultat d'une requête API.

• 2xx : Succès
• 4xx : Erreur client (par exemple, paramètre manquant, Utilisateur introuvable)
• 5xx : Erreur serveur (par exemple, problème interne du serveur)

Codes d'erreur

• 401 : Non autorisé — Clé API invalide.
• 403 : Interdit — Action non autorisée.
• 404 : Introuvable — Ressource non disponible (par exemple, Utilisateur, campagne).
• 500 : Erreur interne du serveur — Veuillez réessayer ultérieurement.
• 503 : Service indisponible — Maintenance en cours.

Considérations de sécurité

Veuillez traiter les clés API avec soin :

• limiter l'accès à la zone de gestion des clés et aux clés créées à un nombre restreint d'employés
• ne pas incorporer les clés API en dur dans votre base de code ni les déposer dans des dépôts de code
• choisir les portées de manière appropriée
• mettre en place un processus de rotation des clés
• supprimer les clés inutiles dès que possible

Conditions générales d'utilisation

La version actuelle des conditions générales d'utilisation est disponible à l'adresse https://support.sosafe.de/INFO/sosafe-api-terms-and-conditions.