1️⃣ Qu'est-ce que l'API Riot ?
L'API Riot vous permet de récupérer par programmation les données de votre organisation depuis la plateforme Riot : collaborateurs, campagnes de phishing, parcours de sensibilisation, fuites de données, signalements Inbox, et plus encore. Vous pouvez ainsi facilement alimenter vos propres outils internes (BI, SIEM, reporting RH) avec vos métriques cyber.
Il s'agit d'une API REST : les requêtes comme les réponses sont encodées en JSON. L'URL de base est https://public-api.tryriot.com/v1.
👍 Bon à savoir : la documentation technique complète, interactive et toujours à jour (liste des endpoints, schémas de réponse, exemples de code) est disponible sur docs.tryriot.com.
2️⃣ Obtenir votre clé API
L'accès à l'API nécessite une clé API. Cette clé ne se génère pas en self-service : elle est fournie par notre équipe technique.
💡 Pré-requis : l'accès à l'API est une option payante — il n'est pas inclus par défaut dans votre offre. Pour vérifier sa disponibilité, connaître son tarif et obtenir une clé, contactez votre interlocuteur Riot (ou notre équipe via le chat en direct). Chaque clé est :
rattachée à une seule organisation — l'accès et les données sont limités à votre périmètre ;
limitée à des scopes précis (par ex.
awareness:read,simulation:read,breach:read,workspace:read) qui définissent les endpoints accessibles.
3️⃣ S'authentifier
Chaque requête doit inclure votre clé dans l'en-tête x-api-key. Exemple de requête (récupération de la liste des domaines) :
curl 'https://public-api.tryriot.com/v1/domains' --header 'x-api-key: YOUR_API_KEY'
⚠️ Important : votre clé API est un secret. Ne la partagez jamais publiquement (dépôt de code, front-end, e-mail non sécurisé). Si vous pensez qu'elle a été exposée, contactez l'équipe technique pour la révoquer.
4️⃣ Les données accessibles via l'API
Les endpoints sont regroupés par module, à l'image des fonctionnalités de la plateforme :
General — organisation, domaines et collaborateurs (liste, détails, statistiques).
Sensibilisation — parcours, progression des collaborateurs et statistiques de formation.
Simulation — campagnes de phishing, attaques associées et statistiques.
Brèches — fuites de données détectées, statistiques et collaborateurs compromis.
Inbox — signalements d'e-mails et statistiques des tickets Inbox.
Groupes — groupes de collaborateurs et leurs membres.
Slash — statistiques des alertes et des tentatives d'usurpation d'identité.
SCIM — provisioning automatisé des utilisateurs et des groupes (création, mise à jour, suppression).
La plupart des endpoints sont en lecture seule (GET) ; le module SCIM permet en plus de provisionner vos utilisateurs et vos groupes. Le détail de chaque endpoint est disponible sur docs.tryriot.com.
5️⃣ Pagination & limites de débit
Pagination : les endpoints qui renvoient une liste utilisent une pagination par curseur. Vous pouvez définir le paramètre limit (50 par défaut, 100 maximum). La réponse contient un objet metadata avec un next_cursor : passez cette valeur dans le paramètre cursor de votre requête suivante pour obtenir la page suivante (next_cursor vaut null sur la dernière page).
Limites de débit : elles s'appliquent par clé API. En cas de dépassement, l'API renvoie un code de statut 429 jusqu'au début de la fenêtre de temps suivante. Les seuils exacts sont définis par l'équipe technique.
👍 Bon à savoir : pour provisionner des utilisateurs via SCIM avec Microsoft Entra, consultez l'article dédié Comment utiliser le provisioning SCIM Microsoft Entra.