1️⃣ What is the Riot API?
The Riot API lets you programmatically retrieve your organization's data from the Riot platform: employees, phishing campaigns, awareness courses, breaches, Inbox reports, and more. This makes it easy to feed your own internal tools (BI, SIEM, HR reporting) with your cyber metrics.
It is a REST API: both requests and responses are JSON-encoded. The base URL is https://public-api.tryriot.com/v1.
👍 Good to know: the full, interactive and always up-to-date technical documentation (endpoint list, response schemas, code samples) is available at docs.tryriot.com.
2️⃣ Get your API key
Access to the API requires an API key. This key is not generated in self-service: it is provided by our technical team.
💡 Prerequisites: API access is an optional paid add-on — it is not included by default in your plan. To check availability and pricing, and to obtain a key, contact your Riot point of contact (or our team via live chat). Each key is:
scoped to a single organization — access and data are restricted to your perimeter;
limited to specific scopes (e.g.
awareness:read,simulation:read,breach:read,workspace:read) that define which endpoints can be accessed.
3️⃣ Authenticating
Every request must include your key in the x-api-key header. Example request (retrieving the list of domains):
curl 'https://public-api.tryriot.com/v1/domains' --header 'x-api-key: YOUR_API_KEY'
⚠️ Important: your API key is a secret. Never share it publicly (code repository, front-end, unsecured email). If you believe it has been exposed, contact the technical team to revoke it.
4️⃣ The data available through the API
Endpoints are grouped by module, mirroring the platform's features:
General — organization, domains and employees (list, details, statistics).
Awareness — courses, employee progress and training statistics.
Simulation — phishing campaigns, related attacks and statistics.
Breaches — detected breaches, statistics and compromised employees.
Inbox — email reports and Inbox ticket statistics.
Groups — employee groups and their members.
Slash — alert and impersonation-attempt statistics.
SCIM — automated provisioning of users and groups (create, update, delete).
Most endpoints are read-only (GET); the SCIM module additionally lets you provision your users and groups. The details of each endpoint are available at docs.tryriot.com.
5️⃣ Pagination & rate limits
Pagination: endpoints that return a list use cursor-based pagination. You can set the limit parameter (50 by default, 100 maximum). The response includes a metadata object with a next_cursor: pass this value in the cursor parameter of your next request to get the following page (next_cursor is null on the last page).
Rate limits: they are enforced per API key. If exceeded, the API returns a 429 status code until the next time window begins. The exact thresholds are defined by the technical team.
👍 Good to know: for provisioning users via SCIM with Microsoft Entra, see the dedicated article How to use Microsoft Entra SCIM provisioning.