Emitir un token para un jugador

Versión de la API 2026-10-virile-dragon

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

Avala a uno de tus jugadores y devuelve un token que tu juego o página usa para él durante 15 minutos. El primer token para un player_ref crea un estudiante para ese jugador; los siguientes lo reutilizan. Pide otro cuando el token caduque; nunca se renueva. Requiere un cliente metered.

Ámbitos embed:mint

Parámetros

Lingara-Versionheaderstringopcional: La versión de la API con la que se responde a esta solicitud. Sin ella, un token de acceso recibe la versión a la que está vinculado su cliente, y una solicitud sin token recibe la versión actual. La versión aún en desarrollo solo se alcanza nombrándola aquí. Una versión desconocida responde 400 con el código api_version_unknown. GET /v1/versions enumera las versiones.

Cuerpo de la solicitud `application/json`

player_refstringobligatorio: Tu propia referencia para el jugador: de 1 a 128 bytes de UTF-8, sin caracteres de control. Lingara solo guarda un hash de ella.
scopesarray of string | nullopcional
originstring | nullopcional

Respuestas

200 El token del jugador

tokenstringobligatorio
expires_atstringobligatorio
expires_inintegerobligatorio: Segundos hasta que caduca el token, contados desde esta respuesta. Úsalo cuando no se pueda confiar en el reloj del dispositivo.
subjectstringobligatorio
scopesarray of stringobligatorio
account_linkedbooleanobligatorio

Errores

410application/json: La versión de la API con la que se responde a esta solicitud se ha retirado. Envía una versión admitida en Lingara-Version o vincula el cliente a otra versión.
4XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.
503application/json · text/plain: El servicio no está disponible temporalmente; vuelve a intentarlo tras el número de segundos indicado en Retry-After. Durante el mantenimiento, el cuerpo es texto sin formato en lugar del sobre de error.
5XXapplication/json: La solicitud fue rechazada. code indica el motivo y error lo explica con palabras.

codestringobligatorio: Por qué se rechazó la solicitud, como un código estable con el que ramificar: por ejemplo insufficient_scope (403), rate_limited (429) y, para un cliente con facturación por uso, spend_cap_reached (402) y metered_billing_inactive (402).
errorstringobligatorio

Ejemplo

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

¿Prefieres una biblioteca? Consulta la sección Bibliotecas.