*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 |
Params & Responses
The following examples show possible params to include, and the response of each endpoint:
Enrollments
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 API
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"
}
]
}
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.
ad_id
initial
phone_number
title
company
job_role
team
security_champion
department_number
employee_number
managers_name
managers_employee_number
business_unit
employee_secondary_number
business_unit_description
Assignments Report API
url
GET "/api/v2/assignments"
params
{
limit: integer,
offset: integer
}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 Attempt Report API
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"
}
]
}