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
To get access to the teaching program, send an email to [email protected]
Registering Users (Credentials)
Register users with pre-defined credentials.
Create TryHackMe users on the fly by specifying account details. Once you've used our API to create a user account, you can have your user sign in with your specified credentials.
Request Endpoint:
POST https://tryhackme.com/external/api/register
Request Body:
{ "apiKey" : String, "userId" : String, "username" : String, "email" : String, "password" : String }The apiKey parameter is the API key required to authenticate this request. The userId parameter is a unique string used to represent the user in your system. The username, email, and password parameters are the user's account details, where the username and email must not already be on TryHackMe (otherwise, the account request will fail, returning a verbose response); You should then give the account details used in this request to the user to log in at https://tryhackme.com/login.
Response:
{ "success" : Boolean, "message" : String }
Registering Users (Custom Registration Page)
Register users by generating a custom client registration page for users.
When you want a user to launch into a TryHackMe room, you will send a POST request to the URL below. The apiKey parameter is the API key required to authenticate the request. The userId parameter is a unique string used to represent your user, and the room code is the room's code that the user is trying to access. A successful request will return a 200 status code with a URL:
If the user has not authenticated to TryHackMe through this API endpoint, the URL will point to a unique sign-up page that redirects a user to a room after a successful registration.
If that user has authenticated to TryHackMe through this API endpoint, the URL will automatically enter a user into a room.
POST https://tryhackme.com/external/api/authenticate
The request body parameters are
{ "apiKey": String, "userId": String, "roomCode": String }
Retrieve User Progress
This endpoint returns users' progress in the specified room. The {ROOM-CODE} parameter is the room code from which you want to receive data.
GET https://tryhackme.com/external/api/scoreboard?roomCode={ROOM-CODE}
The API key needs to be provided inside the THM-API-KEY header as follows.
THM-API-KEY: {API-KEY}
The expected successful response is
[ { "username": String, "tasks": [ 1: { "questionNo": Integer, "correct": Boolean, "score": Integer, "timeCorrect": ISO8601 UTC Timestamp } ... ], "score": Integer, "rank": Integer, "avatar": String, "level": Integer } ]Data will only show for users in the room and created through the /API/external/authenticate endpoint. If you've generated a user through this endpoint, they'll also need to sign up and join the room.
Retrieving Users
This endpoint retrieves all the users who have signed up using the API.
GET https://tryhackme.com/external/api/users
The API key needs to be provided inside the THM-API-KEY header as follows.
THM-API-KEY: {API-KEY}
The expected successful response is as follows.
{ "status": true, "users": [ { "username": String, "email": String, "avatar": String, "totalPoint": Number, "monthlyPoints": Number, "dateSignedUp": ISO8601 UTC Datetime } ] }
Remove Users From Room
This endpoint is used to remove a user from a room.
POST https://tryhackme.com/external/api/leaveRoom
The request body parameters are
{ "apiKey": String, "userId": String, "roomCode": String }
Retrieve Rooms
This endpoint retrieves details of public and the user's private rooms on the platform. The user's field is only returned for a room owned/managed by the API user.
GET https://tryhackme.com/external/api/rooms
The API key needs to be provided inside the THM-API-KEY header as follows
THM-API-KEY: {API-KEY}The expected successful response is as follows
[ { "code": String, "title": String, "description": String, "public": Boolean, "users": [String] } ]
Check If Room Exists
This endpoint checks if a room exists on the platform using the {ROOM-CODE} as a URL parameter.
GET https://tryhackme.com/external/api/roomExists?roomCode={ROOM-CODE}
The API key needs to be provided inside the THM-API-KEY header as follows.
THM-API-KEY: {API-KEY}
The expected successful response is as follows.
{ "roomExists": Boolean }
Room Questions
This endpoint is used to retrieve questions associated with a {ROOM-CODE}. This endpoint retrieves inquiries related to public and private rooms owned by the API user.
GET https://tryhackme.com/external/api/questions?roomCode={ROOM-CODE}
The API key needs to be provided inside the THM-API-KEY header as follows
THM-API-KEY: {API-KEY}The expected successful response is as follows
{ "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." }