1️⃣ What is the Riot API?
The Riot API lets you retrieve your organization's data programmatically: employees, phishing campaigns, awareness programmes, data breaches, Inbox reports and more. You can use it to feed your cyber metrics into your own internal tools (BI, SIEM, HR reporting).
It is a REST API: both requests and responses are encoded in JSON. The base URL is https://public-api.tryriot.com/v1.
👍 Good to know: the full technical documentation, interactive and always up to date (list of endpoints, response schemas, code samples), is available at docs.tryriot.com.
2️⃣ Get your API key
💡 Prerequisite: API access depends on your plan. If the API section doesn't appear in your settings, contact your Riot representative or our team via the chat.
Accessing the API requires an API key. You generate and manage your keys yourself from the Admin platform, in Settings > API.
👉 Two possible levels
Workspace: the key only gives access to that workspace's data.
Organization: the key covers all the workspaces in the organization.
Choose the most restricted level that meets your needs.
👉 Who can create a key?
Creating and managing keys requires the developer role, assigned by the account owner (the super admin, identified by a crown 👑). See Manage my Admins.
👉 What a key allows
It is linked to a single organization: access and data are limited to your scope.
It is limited to specific scopes (for example
awareness:read,simulation:read,breach:read,workspace:read) that define which endpoints are accessible.
3️⃣ Authenticate
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 think it has been exposed, contact our team via the chat to have it revoked.
4️⃣ Data available through the API
Endpoints are grouped by module, mirroring the platform's features:
General: organization, domains and employees (list, details, statistics).
Awareness: programmes, employee progress and training statistics.
Simulation: phishing campaigns, related attacks and statistics.
Breaches: detected data breaches, statistics and compromised employees.
Inbox: email reports and Inbox ticket statistics.
Groups: employee groups and their members.
Slash: statistics on alerts and impersonation attempts.
SCIM: automated provisioning of users and groups (creation, update, deletion).
Most endpoints are read-only (GET); the SCIM module also lets you provision your users and groups. Details of each endpoint are available at docs.tryriot.com.
👍 Good to know: if your workspace has switched to Cyber Missions, the Awareness endpoints remain available: they return the progress data for this way of working, with no URL change on your side.
5️⃣ Pagination and rate limit
Pagination: endpoints that return a list use cursor-based pagination. You can set the limit parameter (50 by default, 100 maximum). The response contains a metadata object with a next_cursor: pass this value in the cursor parameter of your next request to get the next page (next_cursor is null on the last page).
Rate limit: it applies per API key. If you exceed it, the API returns a 429 status code until the start of the next time window.
6️⃣ Receive events with webhooks
The API lets you fetch data. Webhooks do the opposite: Riot sends an event to your tool as soon as it happens. You create and manage your endpoints yourself, in Settings > API > Webhooks, with the same developer role.
👉 The available events and the payload format are described in the webhooks section of the documentation.
👍 Good to know: to provision users via SCIM with Microsoft Entra, see the dedicated article How to use the Microsoft Entra SCIM Provisioning Service.
Key takeaways
API keys are managed yourself in the settings, with the developer role.
Each key is limited to one organization and to specific scopes.
The key is passed in the
x-api-keyheader; lists are paginated by cursor.To receive events in real time, use webhooks.