Security Journey API v2
Use this API to send Platform report data to other tools such a business intelligence and data visualization programs.
Security Journey openAPI v2
*We have released a V3 API and recommended using the latest version here.
API Overview
The Security Journey API utilizes REST. The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The Security Journey API uses API keys to authenticate requests. Viewing and managing API keys is a feature within the Security Journey Admin Dashboard. Once you create the API key, include it in the header, using 'ApiKey' as the key and the API key itself as the value. Also make sure to set:
'Content-Type' to 'application/x-www-form-urlencoded'
Your headers should look something like this:
{'Content-Type': 'application/x-www-form-urlencoded', 'ApiKey': <secret>}
All API requests must use HTTPS, and any made over plain HTTP or without authentication will fail. Security Journey uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., the omission of a required parameter, a charge failed, etc.). Codes in the 5xx range indicate an error with Security Journey's servers (these are rare). Below is a summary of the available functions in V2:
| Function | Endpoint |
| List all enrollments (per path) | /api/v2/enrollments |
| List all users progress per level | /api/v2/enrollments/summary |
| List all users | /api/v2/users |
| List all assignments | /api/v2/assignments |
| List all Lesson Attempts | /api/v2/lesson_attempts |
Example Parameters & Responses
The following examples show possible parameters to include and the response of each endpoint:
Enrollments Endpoint
URL
GET "/api/v2/enrollments"
params
{
limit: integer,
offset: integer,
updated_before: DateTime,
updated_after: DateTime,
}
response
{
"path_enrollments": [
{
"email": "test2@test.com",
"first_name": "Anonymous",
"last_name": "User",
"id": 1197,
"role_name": "Security Apprentice",
"status": "paused",
"last_engagement": "2022/02/01 17:14:06",
"progress": "0/20",
"level_name": "White Belt",
"created_at": "2022/02/01 17:14:06",
"updated_at": "2022/02/01 17:14:06",
"completed_at": null,
"required_total": 17,
"required_passed": 0,
"required_progress_percent": 0,
"total_lessons": "20",
"total_passed_lessons": 0,
"passed_lessons": "0",
"progress_percent": 0,
"total": "0/20",
"required": "0/17"
}
Users Report Endpoint
url
GET "/api/v2/users"
params
{
limit: integer,
offset: integer
}
response
{
"users": [
{
"email": "email1@gmail.com",
"first_name": "John",
"last_name": "Doe",
"total_points": 53,
"country": "Italy"
}
]
}
Assignments Report Endpoint
url
GET "/api/v2/assignments"
params
{
"assignments": [
{
"assignment_name": "Test Name",
"email": "hannah_boothe@securityjourney.com",
"first_name": "Anonymous",
"last_name": "User",
"due_date": "2021/06/30 04:00",
"passed": 0,
"total": 39,
"status": "overdue",
"progress": "0 of 39"
}
]
}
response
{
"assignments": [
{
"assignment_name": "Test Name",
"email": "hannah_boothe@securityjourney.com",
"first_name": "Anonymous",
"last_name": "User",
"due_date": "2021/06/30 04:00",
"passed": 0,
"total": 39,
"status": "overdue",
"progress": "0 of 39"
}
]
}
Lesson Attempts Endpoint
url
GET "/api/v2/lesson_attempts"
params
{
limit: integer,
offset: integer
}
response
{
"attempts": [
{
"module_name": "Awareness: Data Security",
"email": "tester@gmail.com",
"user_id": "27",
"first_name": "test",
"last_name": "test",
"status": "consumed",
"watched_video?": "not watched",
"read_transcript?": "not read",
"experiment_passed?": "N/A",
"quizzes": "in_progress",
"last_updated": "2022/03/07 17:28"
}
]
}
Offset and limit parameters explained
Use these parameters if you want to specify an exact number of entries in your output. Limit gives you the desired number of entries. This is set to 1000 by default. Offset lets you decide which index to begin retrieving data. You can combine limit and offset parameters to narrow your output even further.
Examples:
“/users?limit=10” gives you the first 10 users.
“/assignments?offset=2” skips the first 2 assignments and starts on the 3rd.
“/enrollments?limit=10&offset=2” returns enrollments 3-12.
User API Optional Fields
If at least one user in the report has a non-blank value in the fields listed below, that field will be also included in the report.
- business_unit
- company
- country
- department_number
- employee_number
- job_role
- managers_name
- managers_email
- title
- team
- security_champion