Purpose
Cyber Guru provides the ability to retrieve user and team rankings from the platform via a REST API that returns data in JSON format, ready to be integrated into the customer's dashboards, portals, or reporting systems.
Automating data retrieval depends on the customer's processes and architecture, and for this reason, Cyber Guru cannot oversee this aspect.
This guideline contains the instructions and parameters for invoking the service.
Scope
This information applies to the Cyber Security Awareness Cyber Guru 2.0 platform.
Prerequisites
- The customer must have the technological resources needed to call REST APIs.
Procedure
Cyber Guru provides two REST APIs:
Get token:
URL: https://login.platform.cyberguru.eu/realms/{TENANT}/protocol/openid-connect/token
This API allows you to obtain an authorization token. Call parameters (POST method):
- client_id : ext-api
- client_secret : (provided by Cyber Guru)
- grant_type : client_credentials
Get rankings:
URL: https://<host>/ext/report/rankings
This API allows you to retrieve the rankings of users and teams within the company. To call the API, you must provide the previously obtained token as a Bearer token.
The API accepts the following parameters (GET method):
| Parameter | Type | Required | Description |
| type | integer | Yes | 0 = company users, 1 = company teams, 2 = users of a specific team |
| team | string | Only if type = 2 | Name of the team whose ranking you want to retrieve |
| limit | integer | No | Maximum number of results per page (min: 1, max: 1000) |
| page | integer | No | Results page to retrieve (used together with limit) |
Response examples
Company user ranking (type = 0):
{
"accounts": [
{ "position": "1", "firstname": "Mario", "lastname": "Rossi", "team": "Sales EMEA", "points": "36" },
{ "position": "2", "firstname": "Alessandro", "lastname": "Bianchi", "team": "IT Operations", "points": "32" }
]
}
Company team ranking (type = 1):
{
"teams": [
{ "position": "1", "team": "Sales EMEA", "members": "23", "points": "31" },
{ "position": "2", "team": "IT Operations", "members": "34", "points": "26" }
]
}
Ranking of users in a specific team (type = 2, e.g. team = IT Operations):
{
"accounts": [
{ "position": "1", "firstname": "Mario", "lastname": "Bianchi", "team": "IT Operations", "points": "36" },
{ "position": "2", "firstname": "Ciccio", "lastname": "Verdi", "team": "IT Operations", "points": "32" }
]
}
Paginated response:
When the limit and page parameters are used, the response includes a pagination object with the following information:
| Field | Description |
| current_page | Current page |
| per_page | Items per page |
| total_items | Total available items |
| total_pages | Total available pages |
| has_next / has_prev | Indicates if there is a next/previous page |
| next_page / prev_page | Number of the next/previous page (null if not present) |
| first_page / last_page | First and last available page |
Errors
| HTTP Code | Error Code | Description |
| 400 | EXT_1000 | Invalid input parameter (the message indicates which parameter) |
| 404 | EXT_1003 | Error retrieving data |
| 422 | EXT_1007 | The specified path (level_uuid) does not exist |
| 422 | EXT_1008 | The specified team does not exist in the company |
| 500 | EXT_1001 | Token expired or invalid |
Cyber Guru is available to support customers during the configuration and testing phase in the staging environment and, after successful testing, in the production environment.