Applies to:

Business and Enterprise Dojos

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 Dojo 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

/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",

"assessments": "in_progress",


"last_updated": "2022/03/07 17:28"

}

]

}



Did this answer your question?