1️⃣ ¿Qué es la API de Riot?
LaAPI Riot os permite recuperar mediante programación los datos de vuestra organización desde la plataforma Riot: empleados, campañas de phishing, itinerarios de concienciación, fugas de datos, reportes de Inbox y mucho más. Así podéis alimentar fácilmente vuestras propias herramientas internas (BI, SIEM, informes 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 de API
El acceso a la API requiere una clave de API. Ahora podéis generar y gestionar vuestras claves de forma autónoma directamente desde la plataforma de administración, en Ajustes → API Key (una vez generada).
👉 Dos niveles posibles
Workspace : la clave solo da acceso a los datos de ese espacio.
Organización : la clave abarca todos los espacios de la organización.
Elegid el nivel más restringido que cubra vuestra necesidad.
👉 ¿Quién puede crear una clave?
La creación y la gestión de las claves requieren el rol developer, asignado por el propietario de la cuenta (el superadministrador, identificado con una corona 👑).
💡 Requisitos previos: el acceso a la API es una opción de pago : no está incluido por defecto en vuestra oferta. Para comprobar su disponibilidad, conocer su tarifa y obtener una clave, contactad con vuestro interlocutor de Riot (o con nuestro equipo por el chat). Cada clave está:
vinculada a una sola organización : el acceso y los datos se limitan a vuestro perímetro;
limitada a scopes concretos (por ej.
awareness:read,simulation:read,breach:read,workspace:read) que definen los endpoints accesibles.
3️⃣ Autenticarse
Cada petición debe incluir vuestra clave en el encabezado 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 de 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 el equipo técnico para revocarla.
4️⃣ Los datos accesibles mediante la API
Los endpoints se agrupan por módulo, siguiendo las funcionalidades de la plataforma:
General — organización, dominios y empleados (lista, detalles, estadísticas).
Awareness — itinerarios, avance de los empleados y estadísticas de formación.
Simulation — campañas de phishing, ataques asociados y estadísticas.
Breaches — fugas 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 espacio ha pasado al funcionamiento por Cyber Missions, los endpoints de Awareness siguen siendo utilizables: devuelven los datos de avance correspondientes a ese modo de funcionamiento, sin ningún cambio de URL por vuestra parte.
5️⃣ Paginación y límites de peticiones
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 máximo). La respuesta contiene un objeto metadata con un next_cursor : pasad ese 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).
Límites de peticiones: se aplican por clave de API. En caso de superarlos, la API devuelve un código de estado 429 hasta el inicio de la siguiente ventana temporal. Los umbrales exactos los define el equipo técnico.
👍 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?.