1️⃣ ¿Qué es la API de Riot?
La API de Riot os permite recuperar mediante programación los datos de vuestra organización: empleados, campañas de phishing, itinerarios de concienciación, brechas de datos, reportes de Inbox y mucho más. Así podéis alimentar vuestras propias herramientas internas (BI, SIEM, reporting de RR. HH.) con vuestras métricas de ciberseguridad.
Se trata de una API REST: tanto las peticiones como las respuestas están codificadas en JSON. La URL base es https://public-api.tryriot.com/v1.
👍 Es bueno saberlo: la documentación técnica completa, interactiva y siempre actualizada (lista de endpoints, esquemas de respuesta, ejemplos de código) está disponible en docs.tryriot.com.
2️⃣ Obtener vuestra clave API
💡 Requisito previo: el acceso a la API depende de vuestra oferta. Si la sección API no aparece en vuestra configuración, contactad con vuestro interlocutor de Riot o con nuestro equipo a través del chat.
El acceso a la API requiere una clave API. Generáis y gestionáis vuestras claves de forma autónoma desde la plataforma Admin, en Configuración > API.
👉 Dos niveles posibles
Workspace: la clave solo da acceso a los datos de ese workspace.
Organización: la clave cubre todos los workspaces de la organización.
Elegid el nivel más restringido que responda a vuestra necesidad.
👉 ¿Quién puede crear una clave?
La creación y la gestión de las claves requieren el rol de desarrollador, asignado por el propietario de la cuenta (el superadministrador, identificado con una corona 👑). Ved Gestionar mis Administradores.
👉 Qué permite una clave
Está vinculada a una sola organización: el acceso y los datos se limitan a vuestro perímetro.
Está limitada a scopes concretos (por ejemplo
awareness:read,simulation:read,breach:read,workspace:read) que definen los endpoints accesibles.
3️⃣ Autenticarse
Cada petición debe incluir vuestra clave en el header x-api-key. Ejemplo de petición (obtención de la lista de dominios):
curl 'https://public-api.tryriot.com/v1/domains' --header 'x-api-key: YOUR_API_KEY'
⚠️ Importante: vuestra clave API es un secreto. No la compartáis nunca públicamente (repositorio de código, front-end, correo no seguro). Si creéis que ha quedado expuesta, contactad con nuestro equipo a través del chat para revocarla.
4️⃣ Los datos accesibles a través de la API
Los endpoints se agrupan por módulo, igual que las funcionalidades de la plataforma:
General: organización, dominios y empleados (lista, detalles, estadísticas).
Awareness: itinerarios, progreso de los empleados y estadísticas de formación.
Simulation: campañas de phishing, ataques asociados y estadísticas.
Breaches: brechas de datos detectadas, estadísticas y empleados comprometidos.
Inbox: reportes de correos y estadísticas de los tickets de Inbox.
Grupos: grupos de empleados y sus miembros.
Slash: estadísticas de las alertas y de los intentos de suplantación de identidad.
SCIM: aprovisionamiento automatizado de usuarios y grupos (creación, actualización, eliminación).
La mayoría de los endpoints son de solo lectura (GET); el módulo SCIM permite además aprovisionar vuestros usuarios y grupos. El detalle de cada endpoint está disponible en docs.tryriot.com.
👍 Es bueno saberlo: si vuestro workspace ha pasado al funcionamiento por Cyber Missions, los endpoints de Awareness siguen siendo utilizables: devuelven los datos de progreso correspondientes a este modo de funcionamiento, sin ningún cambio de URL por vuestra parte.
5️⃣ Paginación y rate limit
Paginación: los endpoints que devuelven una lista utilizan una paginación por cursor. Podéis definir el parámetro limit (50 por defecto, 100 como máximo). La respuesta contiene un objeto metadata con un next_cursor: pasad este valor en el parámetro cursor de vuestra siguiente petición para obtener la página siguiente (next_cursor vale null en la última página).
Rate limit: se aplica por clave API. Si se supera, la API devuelve un código de estado 429 hasta el inicio de la siguiente ventana de tiempo.
6️⃣ Recibir eventos con los webhooks
La API os permite ir a buscar datos. Los webhooks hacen lo contrario: Riot envía un evento a vuestra herramienta en cuanto se produce. Creáis y gestionáis vuestros endpoints vosotros mismos, en Configuración > API > Webhooks, con el mismo rol de desarrollador.
👉 Los eventos disponibles y el formato de los envíos se describen en la sección de webhooks de la documentación.
👍 Es bueno saberlo: para aprovisionar usuarios mediante SCIM con Microsoft Entra, consultad el artículo dedicado ¿Cómo utilizar el aprovisionamiento SCIM de Microsoft Entra?
Lo que hay que recordar
Las claves API se gestionan de forma autónoma en la configuración, con el rol de desarrollador.
Cada clave está limitada a una organización y a scopes concretos.
La clave se pasa en el header
x-api-key; las listas se paginan por cursor.Para recibir eventos en tiempo real, utilizad los webhooks.