Play tokens

A play token is a share link for exactly one person. The first person to open it is admitted, and the link is theirs from then on. Mint one token per person.

Where play tokens come from

There are two ways to get a play token:

• An LMS launch. Instruqt mints a token on each launch from a learning management system (LMS) connected through the LTI integration option in the Share menu. The launch link carries the token.
• The API. Your own backend mints a token with the generateLabPlayToken mutation and hands its URL to one person. See Mint a play token with the API.

A second person who opens the same link is refused with This link was already used.

Terms on a play token

A play token has the same terms as an embed. They are fixed when the token is minted.

Term	From an LMS launch	From the API
Plays	1. A learner who wants to play again launches the lab from the LMS again, which mints a new token.	maxPlays. Default 1. 0 is unlimited.
Access window	Set by Instruqt.	startWindowSeconds. Default set by Instruqt.
Lab version	The lab’s default branch.	ref. Default is the lab’s default branch.
Expiry	Set by Instruqt. The token stops working a set time after it is minted.

The access window counts from the moment the person opens the link. It controls when they may start the lab, not how long a session runs.

Opening the link does not extend the expiry. After the expiry, the link shows This link has expired, also to the person who opened it. Send the link to the person soon after you mint it.

Mint a play token with the API

The mutation needs your team’s API key. See API keys for how to send it.

mutation {
  generateLabPlayToken(
    labID: "YOUR_LAB_ID"
    ref: "main"
    startWindowSeconds: 86400
    maxPlays: 1
  ) {
    id
    url
    expiresAt
  }
}

Only labID is required. Leave out the other arguments to take their defaults.

Give the returned url to the person who plays the lab. They open it in their browser, or you put it in an iframe on your own page.

Caution

Use the returned url exactly as the API gives it. A token works only on that link. If you add the token to a normal lab link, the player ignores the token and does not admit the person.

Field	Description
id	The play token’s ID.
token	The token itself. The API returns it only in this response.
url	The link that admits one person to the lab. The API returns it only in this response.
labID, teamID	The lab the token is for, and the team that owns it.
ref	The lab version the token plays. Empty when you left out ref, which means the lab’s default branch.
startWindowSeconds	The access window, in seconds.
maxPlays	The play cap. 0 is unlimited.
expiresAt	When the token stops working.

Caution

Store the url only as long as you need to deliver it. Anyone who opens it first takes the token.

The caller needs the content creator role on the team and edit access to the lab. The mutation refuses a startWindowSeconds that is not positive and a negative maxPlays.

How a token is spent

1. The person opens the token’s link. From an LMS, the launch opens it in the learner’s browser.
2. The player admits them and claims the token for them. No play is counted yet.
3. The player shows the lab’s title, description and outline with a Start lab button.
4. They click Start lab. This counts the play and starts the session.
5. If they reload the page while the session is still running, the button reads Resume lab. No second play is counted.

If the lab fails to start, Instruqt gives the play back and they can click Start lab again.

When their plays are spent and they click Start lab again, the player shows You have used all your plays. An LMS learner launches from the LMS again to get a new token. For a token from the API, mint a new one.

Who the end user is

• From an LMS launch, the end user is the learner who is signed in to the LMS.
• From the API, the end user is the browser that first opens the link, the same as for an embed. If they open the link in a different browser, they are refused with This link was already used.

Known gaps

• Play tokens have no page in the Instruqt UI. You cannot list, inspect or revoke them, and their end users do not appear in an end users table.
• The API can mint a play token but cannot read or revoke one.