1️⃣ Che cos'è l'API di Riot?
L'API di Riot vi permette di recuperare in modo programmatico i dati della vostra organizzazione: dipendenti, campagne di phishing, percorsi di sensibilizzazione, violazioni di dati, segnalazioni Inbox e molto altro. Potete così alimentare i vostri strumenti interni (BI, SIEM, reporting HR) con le vostre metriche cyber.
Si tratta di un'API REST: sia le richieste sia le risposte sono codificate in JSON. L'URL di base è https://public-api.tryriot.com/v1.
👍 Buono a sapersi: la documentazione tecnica completa, interattiva e sempre aggiornata (elenco degli endpoint, schemi di risposta, esempi di codice) è disponibile su docs.tryriot.com.
2️⃣ Ottenere la vostra chiave API
💡 Prerequisiti: l'accesso all'API dipende dalla vostra offerta. Se la sezione API non compare nelle vostre impostazioni, contattate il vostro referente Riot o il nostro team tramite la chat.
L'accesso all'API richiede una chiave API. Generate e gestite le vostre chiavi in autonomia dalla piattaforma Admin, in Impostazioni > API.
👉 Due livelli possibili
Workspace: la chiave dà accesso solo ai dati di quel workspace.
Organizzazione: la chiave copre tutti i workspace dell'organizzazione.
Scegliete il livello più ristretto che risponda alla vostra esigenza.
👉 Chi può creare una chiave?
La creazione e la gestione delle chiavi richiedono il ruolo di sviluppatore, assegnato dal proprietario dell'account (il super amministratore, contrassegnato da una corona 👑). Vedete Gestire i miei amministratori.
👉 Cosa consente una chiave
È collegata a una sola organizzazione: l'accesso e i dati sono limitati al vostro perimetro.
È limitata a scope precisi (ad esempio
awareness:read,simulation:read,breach:read,workspace:read) che definiscono gli endpoint accessibili.
3️⃣ Autenticarsi
Ogni richiesta deve includere la vostra chiave nell'header x-api-key. Esempio di richiesta (recupero dell'elenco dei domini):
curl 'https://public-api.tryriot.com/v1/domains' --header 'x-api-key: YOUR_API_KEY'
⚠️ Importante: la vostra chiave API è un segreto. Non condividetela mai pubblicamente (repository di codice, front-end, e-mail non protetta). Se pensate che sia stata esposta, contattate il nostro team tramite la chat per revocarla.
4️⃣ I dati accessibili tramite l'API
Gli endpoint sono raggruppati per modulo, come le funzionalità della piattaforma:
General: organizzazione, domini e dipendenti (elenco, dettagli, statistiche).
Awareness: percorsi, avanzamento dei dipendenti e statistiche di formazione.
Simulation: campagne di phishing, attacchi associati e statistiche.
Breaches: violazioni di dati rilevate, statistiche e dipendenti compromessi.
Inbox: segnalazioni di e-mail e statistiche dei ticket Inbox.
Gruppi: gruppi di dipendenti e relativi membri.
Slash: statistiche degli avvisi e dei tentativi di furto d'identità.
SCIM: provisioning automatizzato di utenti e gruppi (creazione, aggiornamento, eliminazione).
La maggior parte degli endpoint è in sola lettura (GET); il modulo SCIM consente inoltre il provisioning dei vostri utenti e gruppi. Il dettaglio di ogni endpoint è disponibile su docs.tryriot.com.
👍 Buono a sapersi: se il vostro workspace è passato al funzionamento tramite Cyber Mission, gli endpoint Awareness restano utilizzabili: restituiscono i dati di avanzamento corrispondenti a questa modalità di funzionamento, senza alcun cambio di URL da parte vostra.
5️⃣ Paginazione e rate limit
Paginazione: gli endpoint che restituiscono un elenco utilizzano una paginazione tramite cursore. Potete definire il parametro limit (50 per impostazione predefinita, massimo 100). La risposta contiene un oggetto metadata con un next_cursor: passate questo valore nel parametro cursor della richiesta successiva per ottenere la pagina seguente (next_cursor vale null nell'ultima pagina).
Rate limit: si applica per chiave API. In caso di superamento, l'API restituisce un codice di stato 429 fino all'inizio della finestra temporale successiva.
6️⃣ Ricevere eventi con i webhook
L'API vi permette di andare a recuperare i dati. I webhook fanno il contrario: Riot invia un evento al vostro strumento non appena si verifica. Create e gestite i vostri endpoint in autonomia, in Impostazioni > API > Webhooks, con lo stesso ruolo di sviluppatore.
👉 Gli eventi disponibili e il formato degli invii sono descritti nella sezione webhook della documentazione.
👍 Buono a sapersi: per il provisioning degli utenti tramite SCIM con Microsoft Entra, consultate l'articolo dedicato Come utilizzare il provisioning SCIM di Microsoft Entra.
Da ricordare
Le chiavi API si gestiscono in autonomia nelle impostazioni, con il ruolo di sviluppatore.
Ogni chiave è limitata a un'organizzazione e a scope precisi.
La chiave si passa nell'header
x-api-key; gli elenchi sono paginati tramite cursore.Per ricevere eventi in tempo reale, utilizzate i webhook.