Comment utiliser l’API Riot ?

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 : collaborateurs, campagnes de phishing, parcours de sensibilisation, fuites de données, signalements Inbox, et plus encore. Vous pouvez ainsi 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

💡 Pré-requis : l'accès à l'API dépend de votre offre. Si la section API n'apparaît pas dans vos paramètres, contactez votre interlocuteur Riot ou notre équipe via le chat.

L'accès à l'API nécessite une clé API. Vous générez et gérez vos clés en autonomie depuis la plateforme Admin, dans Paramètres > API.

👉 Deux niveaux possibles

Workspace : la clé ne donne accès qu'aux données de ce workspace.
Organisation : la clé couvre l'ensemble des workspaces de l'organisation.

Choisissez le niveau le plus restreint qui réponde à votre besoin.

👉 Qui peut créer une clé ?

La création et la gestion des clés demandent le rôle développeur, attribué par le propriétaire du compte (le super administrateur, identifié par une couronne 👑). Voir Gérer les Administrateurs.

👉 Ce que permet une clé

Elle est rattachée à une seule organisation : l'accès et les données sont limités à votre périmètre.
Elle est limitée à des scopes précis (par exemple 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 le header 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 notre équipe via le chat 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 : provisionnement 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.

👍 Bon à savoir : si votre workspace est passé au fonctionnement par Cyber Missions, les endpoints Sensibilisation restent utilisables : ils renvoient les données de progression correspondant à ce mode de fonctionnement, sans changement d'URL de votre côté.

5️⃣ Pagination et rate limit

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).

Rate limit : il s'applique 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.

6️⃣ Recevoir des événements avec les webhooks

L'API vous permet d'aller chercher des données. Les webhooks font l'inverse : Riot envoie un événement à votre outil dès qu'il se produit. Vous créez et gérez vos endpoints vous-même, dans Paramètres > API > Webhooks, avec le même rôle développeur.

👉 Le détail des événements disponibles et du format des envois est décrit dans la section webhooks de la documentation.

👍 Bon à savoir : pour provisionner des utilisateurs via SCIM avec Microsoft Entra, consultez l'article dédié Comment utiliser le provisioning SCIM de Microsoft Entra.

À retenir

Les clés API se gèrent en autonomie dans les paramètres, avec le rôle développeur.
Chaque clé est limitée à une organisation et à des scopes précis.
La clé se passe dans le header x-api-key ; les listes sont paginées par curseur.
Pour recevoir des événements en temps réel, utilisez les webhooks.