Mint a token for a player

Parameters

Lingara-Versionheaderstringoptional

The API version to answer this request under. Without it, an access token gets the version its client is pinned to, and a request with no token gets the current version. The version still in development is reached only by naming it here. An unknown version answers 400 with code api_version_unknown. GET /v1/versions lists the versions.

Request body application/json

player_refstringrequired

Your own reference for the player: 1 to 128 bytes of UTF-8, with no control characters. Lingara stores only a hash of it.

scopesarray of string | nulloptional

originstring | nulloptional

Responses

200 The player's token

tokenstringrequired

expires_atstringrequired

expires_inintegerrequired

Seconds until the token expires, counted from this answer. Use it when the device's clock cannot be trusted.

subjectstringrequired

scopesarray of stringrequired

account_linkedbooleanrequired

Errors

410application/json

The API version this request is answered under has been discontinued. Send a supported version in Lingara-Version, or re-pin the client.

4XXapplication/json

The request was refused. code says why, and error says it in words.

503application/json · text/plain

The service is temporarily unavailable; retry after the number of seconds in Retry-After. During maintenance the body is plain text rather than the error envelope.

5XXapplication/json

The request was refused. code says why, and error says it in words.

codestringrequired

Why the request was refused, as a stable code to branch on: for example insufficient_scope (403), rate_limited (429) and, for a metered client, spend_cap_reached (402) and metered_billing_inactive (402).

errorstringrequired

Example

curl -X POST "https://api.getlingara.com/v1/embed/tokens" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"player_ref":"player-1001","scopes":["embed:play","lesson_plans:read","lesson_plans:write"],"origin":"https://game.example.com"}'

Prefer a library? See the Libraries section.