Skip to main content

Enterprise API

Learn how to use the TryHackMe API to manage users, rooms, and reporting for Business and Classroom plans.

Blackout avatar
Written by Blackout
Updated this week

Instructors that are part of the TryHackMe Business or Classroom plans get access to a set of API features that they can use to perform various functions such as:

  • register/authenticate users

  • retrieve users' room data

  • retrieve public rooms

Registering API-Users to Platform

Create TryHackMe account for company/client api-user, if the user successfully registers their email gets updated on company api-user.

This link will show a custom message, company logo, and company name when you get to the signup page.

Request Endpoint:

GET <https://tryhackme.com/external/api/register?token={api-user-token}>

Response:

Success redirects to ‘/signup’, Fail redirects to ‘/404

Authenticate API-Users

Add new api-user to company and return registration link **and has the following scenarios:

  • If api-user does not exist, add them to the company api-users and give link to register.

  • If api-user exists but not registered, returns link to register to the platform.

  • If api-user exists and is registered, returns link to join the room.

Request Endpoint:

POST <https://tryhackme.com/external/api/authenticate>

Headers:

THM-API-KEY: {api-key}

Body:

{ "extUserId": String, // unique external user id for adding to api-users "roomCode": String // TryHackMe room code }

Response:

{ "url": string }

Add/Remove user from Seat

This endpoint can be used to add (PUT) or remove (DELETE) a user from a seat in your management dashboard.

Request Endpoint:

PUT <https://tryhackme.com/api/v2/external/seats/users> (to add a user to a seat)

DELETE <https://tryhackme.com/api/v2/external/seats/users> (to remove a user from a seat)

Headers:

THM-API-KEY: {api-key}

Body:

{ "email": String }

Response:

{ "status": "success", "data": { "username": String } }

Error handling:

403 FORBIDDEN - Invalid or Missing API key:

{ "status": "error", "message": "API Key is invalid or has expired.", "stack": "Error: API Key is invalid or has expired. ..." }

400 BAD REQUEST - email missing from request body:

{ "status": "error", "message": "email is required.", "stack": "Error: email is required. ..." }

The below errors are returned by the PUT endpoint

400 BAD REQUEST - email not found (no user exists with this email):

{ "status": "error", "message": "email not found.", "stack": "Error: email not found. ..." }

400 BAD REQUEST - No available seats in dashboard.

{ "status": "error", "message": "no available seats in dashboard.", "stack": "Error: no available seats in dashboard. ..." }

400 BAD REQUEST - User already assigned to seat.

{ "status": "error", "message": "User already assigned to seat.", "stack": "Error: User already assigned to seat. ..." }

The below errors are returned by the DELETE endpoint

400 BAD REQUEST - User is not currently in a company seat.

{ "status": "error", "message": "User is not currently in a company seat.", "stack": "Error: User is not currently in a company seat. ..." }

Room Scoreboard

This endpoint returns the score and attempts your users have made in a particular room. Use the room-code as a URL parameter. Reminder: the room code is the final string in the room’s URL, i.e. https://tryhackme.com/room/{room-code}

Request Endpoint:

GET <https://tryhackme.com/api/v2/external/scoreboard?roomCode={room-code}>

Headers:

THM-API-KEY: {api-key}

Response:

{ "status": "success", "data": Array<{ "score": Number, "tasks": Record< String, Array<{ "correct": Boolean, "score": Number, "attempts": Number, "_id": String, "questionNo": Number, "timeCorrect": ISODateString, }> >; "level": Number, "avatar": String, "username": String, "rank": Number, }>; }

Error Handling:

403 FORBIDDEN - Invalid or Missing API key:

{ "status": "error", "message": "API Key is invalid or has expired.", "stack": "Error: API Key is invalid or has expired. ..." }

400 BAD REQUEST - roomCode query parameter is mandatory:

{ "status": "error", "message": "roomCode query parameter is mandatory", "stack": "Error: roomCode query parameter is mandatory. ..." }

404 NOT FOUND - Room not found:

{ "status": "error", "message": "Room not found.", "stack": "Error: Room not found. ..." }

Retrieving Users

This endpoint retrieves users on seats of company and api-users if they have registered to platform.

Request Endpoint:

GET <https://tryhackme.com/external/api/users>

Headers:

THM-API-KEY: {api-key}

Response:

{ "status": true, "users": [ { "username": String, "email": String, "avatar": String, "totalPoint": Number, "monthlyPoints": Number, "dateSignedUp": ISO8601 UTC Datetime, "extUserId": String // only for api-users }, ] }

Remove Users From Room

This endpoint is used to remove a user (mark as left) from a room.

Request Endpoint:

POST <https://tryhackme.com/external/api/leaveRoom>

Headers:

THM-API-KEY: {api-key}

Body:

{ "extUserId": String, "roomCode": String }

Response:

{ }

Retrieve Rooms

This endpoint retrieves details of public and the user's private rooms on the platform.

Request Endpoint:

GET <https://tryhackme.com/external/api/rooms>

Headers:

THM-API-KEY: {api-key}

Response:

{ "roomInfo":[ { "code": String, "title": String, "description": String, "public": Boolean, } ] }

Check If Room Exists

This endpoint checks if a public room and the user's private rooms exists on the platform using the room-code as a URL parameter.

Request Endpoint:

GET <https://tryhackme.com/external/api/roomExists?roomCode={room-code}>

Headers:

THM-API-KEY: {api-key}

Response:

{ "roomExists": Boolean }

Room Questions

This endpoint is used to retrieve questions associated with a room-code, retrieves inquiries related to public rooms and private rooms owned by the client/company.

Request Endpoint:

GET <https://tryhackme.com/external/api/questions?roomCode={room-code}>

Headers:

THM-API-KEY: {api-key}

Response:

{ "questions": [ { "taskNo": Integer, "infoList":[ { "questionNo": Integer, "question": String, "answer": String, "hint": String, "extraPoints": Integer } ] } ] }

Status Codes & Error Handling

A successful request to any endpoint will always return a 200 OK response.

A request to an endpoint that does not return a 200 OK response will contain a message parameter attached to the reaction as follows.

{ "message": "API Key is invalid or has expired." }

Contact

  • Existing B2B or EDU customer and have questions? Please contact your Customer Success Manager or Technical Support.

  • Please contact [email protected] if you'd like to explore whether TryHackMe could be a good fit for your organization. Alternatively, book a meeting directly with the Sales team: For Education, For Business

TryHackMe

Did this answer your question?