Lessonspace

Quickstart

Authentication

Authentication in the Launch API is done using your organisation's API key which can be found in the developer settings of your organisation's dashboard.

Token

Simply add the Authorization header, set to Organisation {{ API_KEY }} to authenticate your request.

The Launch Endpoint

The Launch API is largely centered around the - rather unsurprisingly named - launch endpoint. This endpoint serves multiple purposes; being the first port of call when retrieving an existing space, creating a new space and even joining a space. It's main purpose is to abstract away the boilerplate of organisation management associated with creating and joining spaces.

As mentioned in the terms and concepts Lessonspace uses the room.sh API to provide the collaborative environment for its spaces. Let's start by trying out the launch endpoint right now. It supports many optional parameters, but the only one that's required is id.

The id field uniquely identifies the space to join, and can be any identifier of your choosing (with a maximum length of 64 characters). If the specified id has never been used with the launch endpoint before (for a specific API key that is) then a new Space will be created. Alternatively, setting a previous used id will simply retrieve the existing space.

A useful id can be some sort of relationship identifier of the people in the space, for example, student123_tutor456.

As one might expect, a response with a status code of 201 means that a new space a been created. A status code of 200 means that an existing space has been retrieved.

When creating a Space using the launch endpoint, you can set a name for the space using the name field. If the name field is not specified then the id will be used a placeholder. Alternatively, you can include a null or blank value in the name field, which will result in the space having a null or blank name.

Using the space

Five things were returned from our call to the launch endpoint; client_url, api_base, room_id, session_id and secret. Let's look at the client_url field. This is the raw URL of the space itself (you may notice that it's a room.sh link rather than a Lessonspace one). This URL will allow you to join the space as a guest (assuming that allow_guests has been set to true of course). Try open it in your browser and you should be greeted by the lobby screen:

You can find more information on the other fields by checking out the endpoint specification in our API reference.

Identifying users

The call above only allowed you to join the space as a guest. This is because we didn't specify any user information in our API call. Let's create two URLs for the same space, one for Alice:

and one for Bob:

We'd normally send the first client_url to Alice, and the second to Bob; but if you don't have an Alice or a Bob nearby, you can open them both up in your browser in two separate tabs.

If you look carefully at the client_url field for both Alice and Bob, you'll see a user query parameter; the value of which is their signed JWT which is used to identify them. As such, it's very important that these client URLs are never shared between users.

You can specify an id in the user object, to uniquely identify users with the same name, or for linking data for analytics. By default, the id field takes on the same value as name. This id can be any identifier of your choosing, and is handled opaquely. Also, make sure to add the email field to the payload so as to allow the Lessonspace API to correctly identify each user and their corresponding Lessonspace account (don't worry, if you specify an email that doesn't exist in your organisation the user will be automatically added to your organisation as a student)

Embedding a space

The space supports being embedded in an iframe - you'll want to ensure you set the allow attribute so that all features of the space work correctly. You can copy and paste the snippet below and replace the src of the iframe tag with the client_url you generated from the above launch endpoint.

<iframe src="CLIENT_URL_GOES_HERE"
        allow="camera; microphone; display-capture"
        frameborder="0">
</iframe>