Restricting Access
When calling the launch endpoint, optional parameters can be passed to generate a client_url with certain restrictions.
Time-based restrictions
Generate a link that is only valid for a given time
The timeframe for which a generated link can be used can be limited by specifying a timeouts parameter. This is not a global limit on the Space, but rather link-specific. This means it is possible to generate a link for one user, allowing them to join now, and a link for another user where they can only join at a later time.
The structure for the timeouts parameter is as follows:
"timeouts": {
"not_before": "2019-12-12T06:00",
"not_after": "2019-12-12T08:00",
}
not_before is an ISO8601 timestamp that specifies the earliest time that a link can be used to join a Space.
not_after is an ISO8601 timestamp that specifies the latest time that a link can be used to join a Space. It will stop new users from joining and also stop existing users from rejoining.
For example, the following request would generate a URL valid for the next hour (from ):
{
"request": {
"method": "POST",
"url": "https://api.thelessonspace.com/v2/spaces/launch/",
"headers": [
{
"name": "Authorization",
"value": "Organisation __API_KEY__"
}
],
"postData": {
"mimeType": "application/json",
"text" : "{\"id\": \"space 1\", \"user\": {\"name\": \"Alice\"}, \"timeouts\": {\"not_before\": \"{{useDatetime().now().toISO()}}\", \"not_after\": \"{{useDatetime().now().plus({ minutes: 60 }).toISO()}}\"}}"
}
},
"response": {
"status": 200,
"httpVersion": "HTTP/2",
"headers": [
{
"name": "content-type",
"value": "application/json"
}
],
"content": {
"text": "{\"client_url\": \"https://go.room.sh/...\", \"api_base\": \"https://ew2-aa.room.sh/v1/room/uuid\", \"room_id\": \"uuid\", \"secret\": \"uuid\", \"session_id\": \"uuid\", \"user_id\": \"int\"}",
"mimeType": "application/json"
}
}
}
Using timeouts.not_after will not kick any current users out of the Space and users will still be able to use some of the whiteboard tools. However, they will not be able to make API requests and therefore some functionalities like loading a new image and exporting the room will be disabled.
End a session at a particular time
Suppose you want to have a session that should last 30 minutes. If you want the session to automatically end at a predetermined time and kick all users, this can be achieved by using a combination of the timeouts.not_before and timeouts.not_after parameters mentioned above, and the user.custom_jwt_parameters parameter.
By setting the kickOnExp (meaning "kick on expiry") attribute of the custom_jwt_parameters to true, that user will be kicked out of the Space when the time specified in the not_after timestamp is reached.
A full example payload would look something like:
{
"id": "example-id",
"user": {
"name": "Test User",
"custom_jwt_parameters": {
"kickOnExp": true
}
},
"timeouts": {
"not_before": "2022-08-10 10:27:00.000",
"not_after": "2022-08-10 10:29:00.000"
}
}
Prompt users about the session ending
It is possible to create a "soft" limit on the end of a session and prompt users at a predetermined time. The leader will have the option to extend the session by 10 minutes. At the end of these 10 minutes, the leader will be prompted again.
This is achieved by using the user.custom_jwt_parameters.softExp field and passing the desired time to send the prompt in UNIX seconds time format.
"custom_jwt_parameters": {
"softExp": 1660740441 // Wed, 17 Aug 2022 12:47:21 GMT (Time in UNIX epoch seconds)
}
Moreover, this can be used in combination with the timeouts parameter and user.custom_jwt_parameters.kickOnExp fields to create "hard" limits on the beginning and end of the session. The session will not be accessible before the time given in timeouts.not_before and users will be kicked once the time given in timeouts.not_after is reached. A full example payload would look something like this:
{
"id": "space 1",
"user": {
"name": "Alice",
"leader": true,
"custom_jwt_parameters": {
"kickOnExp": true,
"softExp": 1660740441 // Wed, 17 Aug 2022 12:47:21 GMT (Time in UNIX epoch seconds)
}
},
"timeouts": {
"not_before": "2022-08-17T12:00:00+00:00",
"not_after": "2022-08-17T13:00:00+00:00"
}
}
Session-based restrictions
Calling the Launch endpoint can also be used to assign restrictions to Sessions when being created. These will apply to anyone who joins with that specific client_url.
These are not global restrictions on the Space, but rather link-specific. Different users may have different restrictions.
Generate a single-use link
To generate a link that will be valid only once, set the single_use key to true. After a user has joined the Space via the client_url, other users will be blocked from entering the Space using the same link.
The first user can still rejoin the session if they are disconnected or reload the page, as long as they rejoin before the session ends. This link cannot be shared with other users or reused later on.
Body Schema
{
"id": "biology101-2023",
"user":
{
"id":"BioStudent_2",
"name":"Barry Allen",
"role": "student",
"email":"barry@fast.co.za",
"leader":false,
"single_use": true, // All we need to add
"custom_jwt_parameters":
{
"meta":
{
"displayName": "The Flash"
}
}
}
}
A session will automatically end 30 seconds after the last user has left, or if all users in the space have been idle for 5 minutes.
Time-related restrictions
Generate a link that is only valid for a given time
The timeframe for which a generated link can be used can be limited by specifying a timeouts parameter. This means it is possible to generate a link for one user, allowing them to join now, and a link for another user where they can only join at a later time.
The structure for the timeouts parameter is as follows:
"timeouts": {
"not_before": "2019-12-12T06:00",
"not_after": "2019-12-12T08:00"
}
not_before is an ISO8601 timestamp that specifies the earliest time that a link can be used to join a Space.
not_after is an ISO8601 timestamp that specifies the latest time that a link can be used to join a Space. It will stop new users from joining and also stop existing users from rejoining (including if they disconnect and automatically try to rejoin).
Using timeouts.not_after by itself will not kick any current users out of the Space when the timeout is reached. Users already in the Space will still be able to use some of the whiteboard tools. However, they will not be able to make API requests and therefore some functionality (such as uploading a new image or exporting the room) will not work.
Body Schema
{
"id": "biology101-2023",
"user":
{
"id": "BioStudent_2",
"name": "Barry Allen",
"role": "student",
"email": "barry@fast.co.za",
"leader": false,
"single_use": true,
"custom_jwt_parameters":
{
"meta":
{
"displayName": "The Flash"
}
}
},
"timeouts":
{
"not_before": "2023-12-12T06:00",
"not_after": "2023-12-12T08:00"
}
}
How to forcibly end a session at a particular time
Suppose you want to have a session that should last 30 minutes. If you want the session to automatically end at a predetermined time and kick all users, this can be achieved by using a combination of the timeouts.not_before and timeouts.not_after parameters mentioned above, and the user.custom_jwt_parameters parameter.
By setting the kickOnExp (meaning "kick on expiry") attribute of the custom_jwt_parameters to true, that user will be kicked out of the Space when the time specified in the not_after timestamp is reached.
A full example payload would look something like:
Body Schema
{
"id": "biology101-2023",
"user":
{
"id": "BioStudent_2",
"name": "Barry Allen",
"role": "student",
"email": "barry@fast.co.za",
"leader": false,
"single_use": true,
"custom_jwt_parameters":
{
"kickOnExp": true,
"meta":
{
"displayName": "The Flash"
}
}
},
"timeouts":
{
"not_before": "2023-12-12T06:00",
"not_after": "2023-12-12T08:00"
}
}
Prompt users about the session ending
It is possible to create a "soft" limit on the end of a session and prompt leaders to act accordingly. The leader will have the option to extend the session by 10 minutes. At the end of these 10 minutes, the leader will be prompted again.
This is achieved by using the user.custom_jwt_parameters.softExp field and passing the desired time to send the prompt in Unix/POSIX time format.
"custom_jwt_parameters": {
"softExp": 1660740441 // Wed, 17 Aug 2022 12:47:21 GMT (Time in UNIX epoch seconds)
}
Moreover, this can be used in combination with the timeouts parameter and user.custom_jwt_parameters.kickOnExp fields to create "hard" limits on the beginning and end of the session. The session will not be accessible before the time given in timeouts.not_before and users will be kicked once the time given in timeouts.not_after is reached. A full example payload would look something like this:
Body Schema
{
"id": "biology101-2023",
"user":
{
"id": "BioStudent_2",
"name": "Barry Allen",
"role": "student",
"email": "barry@fast.co.za",
"leader": false,
"single_use": true,
"custom_jwt_parameters":
{
"kickOnExp": true,
"softExp": 1660740441, // Wed, 17 Aug 2022 12:47:21 GMT (Time in UNIX epoch seconds)
"meta":
{
"displayName": "The Flash"
}
}
},
"timeouts":
{
"not_before": "2022-08-17T12:00:00+00:00",
"not_after": "2022-08-17T13:00:00+00:00"
}
}