Emitir um token para um jogador

Versão da API 2026-10-virile-dragon

post https://api.getlingara.com/v1/embed/tokens

Garante um dos seus jogadores e devolve um token que o seu jogo ou página usa para ele durante 15 minutos. O primeiro token para um player_ref cria um aluno para esse jogador; os seguintes reutilizam-no. Peça outro quando o token expirar; ele nunca é renovado. Requer um cliente metered.

Âmbitos embed:mint

Parâmetros

Lingara-Versionheaderstringopcional: A versão da API com que responder a este pedido. Sem ela, um token de acesso recebe a versão a que o seu cliente está associado, e um pedido sem token recebe a versão atual. A versão ainda em desenvolvimento só é alcançada indicando-a aqui. Uma versão desconhecida responde 400 com o código api_version_unknown. GET /v1/versions lista as versões.

Corpo do pedido `application/json`

player_refstringobrigatório: A sua própria referência para o jogador: de 1 a 128 bytes de UTF-8, sem caracteres de controlo. A Lingara guarda apenas um hash dela.
scopesarray of string | nullopcional
originstring | nullopcional

Respostas

200 O token do jogador

tokenstringobrigatório
expires_atstringobrigatório
expires_inintegerobrigatório: Segundos até o token expirar, contados a partir desta resposta. Use-o quando não for possível confiar no relógio do dispositivo.
subjectstringobrigatório
scopesarray of stringobrigatório
account_linkedbooleanobrigatório

Erros

410application/json: A versão da API com que este pedido é respondido foi descontinuada. Envie uma versão suportada em Lingara-Version, ou associe o cliente a outra versão.
4XXapplication/json: O pedido foi recusado. code indica o motivo e error descreve-o por palavras.
503application/json · text/plain: O serviço está temporariamente indisponível; tente novamente após o número de segundos indicado em Retry-After. Durante a manutenção, o corpo é texto simples em vez do envelope de erro.
5XXapplication/json: O pedido foi recusado. code indica o motivo e error descreve-o por palavras.

codestringobrigatório: O motivo pelo qual o pedido foi recusado, como um código estável para ramificar a lógica: por exemplo insufficient_scope (403), rate_limited (429) e, para um cliente com faturação por utilização, spend_cap_reached (402) e metered_billing_inactive (402).
errorstringobrigatório

Exemplo

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"}'

Prefere uma biblioteca? Veja a secção Bibliotecas.