Enterprise API
G
Written by Gonzo
Updated over a week ago

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." }
Did this answer your question?