1️⃣ Che cos'è l'API di Riot?

L'API di Riot vi permette di recuperare a livello programmatico i dati della vostra organizzazione dalla piattaforma Riot: collaboratori, campagne di phishing, percorsi di sensibilizzazione, fughe di dati, segnalazioni Inbox e molto altro. Potete così alimentare facilmente 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

L'accesso all'API richiede una chiave API, che generate e gestite in autonomia direttamente dalla piattaforma, in Impostazioni > API Key.

👉 Due livelli possibili

Workspace: la chiave dà accesso soltanto ai dati di quello spazio.
Organizzazione: la chiave copre l'insieme degli spazi 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 developer, assegnato dal proprietario dell'account (il super amministratore, contrassegnato da una corona 👑). Vedete Gestire i miei amministratori.

💡 Prerequisiti: l'accesso all'API è un'opzione a pagamento — non è incluso per impostazione predefinita nella vostra offerta, e deve essere attivato sul vostro spazio dai nostri team. Per verificarne la disponibilità e conoscere il prezzo, contattate il vostro referente Riot o il nostro team tramite la chat. Ogni chiave è:

collegata a un unico perimetro (un workspace o un'organizzazione) — accesso e dati sono limitati a quello;
limitata a scope precisi (per es. 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 ritenete che sia stata esposta, contattate il team tecnico per revocarla.

4️⃣ I dati accessibili tramite l'API

Gli endpoint sono raggruppati per modulo, rispecchiando le funzionalità della piattaforma:

General — organizzazione, domini e collaboratori (elenco, dettagli, statistiche).
Awareness — percorsi, avanzamento dei collaboratori e statistiche di formazione.
Simulation — campagne di phishing, attacchi associati e statistiche.
Breaches — fughe di dati rilevate, statistiche e collaboratori compromessi.
Inbox — segnalazioni di e-mail e statistiche dei ticket Inbox.
Groups — gruppi di collaboratori e relativi membri.
Slash — statistiche degli avvisi e dei tentativi di impersonificazione.
SCIM — provisioning automatizzato di utenti e gruppi (creazione, aggiornamento, eliminazione).

La maggior parte degli endpoint è in sola lettura (GET); il modulo SCIM permette inoltre di effettuare il provisioning di utenti e gruppi. Il dettaglio di ogni endpoint è disponibile su docs.tryriot.com.

👍 Buono a sapersi: se il vostro spazio è passato al funzionamento tramite Cyber Mission, gli endpoint Awareness restano utilizzabili: restituiscono i dati di avanzamento corrispondenti a questa modalità, senza alcun cambiamento di URL dal vostro lato.

5️⃣ Paginazione e limiti di frequenza

Paginazione: gli endpoint che restituiscono un elenco utilizzano una paginazione a cursore. Potete definire il parametro limit (50 per impostazione predefinita, 100 al massimo). 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).
Limiti di frequenza: si applicano per chiave API. In caso di superamento, l'API restituisce un codice di stato 429 fino all'inizio della finestra temporale successiva. Le soglie esatte sono definite dal team tecnico.

👍 Buono a sapersi: per effettuare il provisioning degli utenti tramite SCIM con Microsoft Entra, consultate l'articolo dedicato Come utilizzare il provisioning SCIM di Microsoft Entra.

Come utilizzare l'API di Riot?