Autenticación

Versión de la API 2026-10-affable-towhee

Cada llamada a la API de Lingara lleva un token de acceso. Un servidor obtiene uno intercambiando el ID de cliente y el secreto de un cliente OAuth en el endpoint de tokens: la concesión client credentials de OAuth 2.0, para un servidor que actúa en su propio nombre. Crea clientes en la página Integraciones de la aplicación web de Lingara, en app.getlingara.com/admin.

Una sesión o un cliente

Las aplicaciones de Lingara te identifican con una sesión, que tiene todos los ámbitos y consume la cuota de tu plan. Un cliente es más limitado: eliges los ámbitos que tiene permitidos al crearlo, y cada token de acceso que obtiene lleva solo los ámbitos que solicita.

Tres valores

El ID de cliente empieza por lgr_cid_ e identifica al cliente ante el endpoint de tokens. No es secreto.

El secreto del cliente empieza por lgr_cs_ y solo se envía al endpoint de tokens. Se muestra una sola vez, al crearlo: cópialo entonces, porque Lingara solo guarda un hash de él.

El token de acceso empieza por lgr_at_ y dura una hora. Va en la cabecera Authorization: Bearer de las llamadas bajo /v1/, y en ningún otro sitio. Es el único valor que corresponde a esa cabecera: un secreto de cliente enviado ahí se rechaza con 401.

Obtén un token de acceso

Envía un formulario con POST al endpoint de tokens con grant_type=client_credentials. Envía el ID de cliente y el secreto mediante autenticación HTTP Basic o como los campos de formulario client_id y client_secret, nunca ambos. scope es una lista, separada por espacios, de ámbitos permitidos al cliente; omítela para obtener todos los ámbitos que el cliente tiene permitidos. El comando siguiente solo solicita usage:read, el ámbito que necesita el ejemplo GET /v1/usage más abajo.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

La respuesta contiene access_token, token_type (Bearer), expires_in (3600, en segundos) y scope, los ámbitos que el token tiene realmente. Un intercambio fallido responde con el formato de error de OAuth, {error, error_description}, no con el sobre {code, error} de /v1/. Un secreto incorrecto o revocado, o un cliente eliminado, se rechaza con 401 e invalid_client. Un ámbito que el cliente no puede solicitar hace que se rechace todo el intercambio con 400 e invalid_scope; nunca se restringe en silencio.

Actúa en nombre de otro usuario de Lingara

Una aplicación que actúa en nombre de otro usuario de Lingara usa la concesión de código de autorización. Envía el navegador del usuario a la URL de autorización con response_type=code, client_id, una redirect_uri que coincida exactamente con una que hayas registrado, scope, state y un code_challenge S256. El usuario ve la página de consentimiento de Lingara y vuelve a tu redirect_uri con code, state e iss. Comprueba que state es el que enviaste y que iss es https://api.getlingara.com antes de usar el código.

PKCE es obligatorio

Todos los clientes usan PKCE, solo con el método S256. Genera un code_verifier aleatorio, envía su hash SHA-256, codificado en base64url, como code_challenge con code_challenge_method=S256, y guarda el verificador para el intercambio. Una solicitud sin método, o con plain, se rechaza con invalid_request.

Intercambia el código

En un plazo de 60 segundos, envía con POST al endpoint de tokens grant_type=authorization_code, code, la misma redirect_uri y el code_verifier, autenticándote como el cliente; un cliente público envía solo client_id. La respuesta añade un refresh_token, que empieza por lgr_rt_. El código empieza por lgr_ac_ y funciona una sola vez: un segundo uso se rechaza con invalid_grant y pone fin a los tokens que emitió el primer intercambio.

Renueva

Cuando el token de acceso caduque, envía con POST al endpoint de tokens grant_type=refresh_token y el refresh_token, autenticándote de nuevo como el cliente. Cada renovación devuelve un nuevo token de actualización: conserva solo el más reciente. Haz tus renovaciones de una en una: un token de actualización antiguo usado más de 60 segundos después de ser sustituido se considera robado y pone fin a los tokens de esa instalación con invalid_grant. Un token de actualización que no se usa durante 30 días caduca. El endpoint de tokens limita las solicitudes por dirección, así que renueva solo cuando un token se agote.

Las aplicaciones nativas son clientes públicos

Una aplicación de escritorio, móvil o de línea de comandos no puede guardar un secreto, así que es un cliente público: no tiene secreto, envía solo client_id al endpoint de tokens y registra una redirección de loopback como http://127.0.0.1/callback (cualquier puerto) o un esquema de uso privado como com.example.app:/callback. El usuario ve la página de consentimiento cada vez. Una página web no puede ser un cliente: ni el endpoint de tokens ni /v1/ responden a una solicitud preliminar entre orígenes.

Cuando el usuario quita tu aplicación

El usuario puede quitar tu aplicación en cualquier momento en Aplicaciones conectadas, o desinstalándola si la instaló, y su siguiente llamada falla con 401. Cuando el usuario cierre sesión en tu aplicación, revoca su token de actualización en el endpoint de revocación, lo que pone fin a los tokens de esa instalación.

Cuando el token caduca

Pasada una hora, /v1/ responde 401 con el código unauthorized y un error que empieza por invalid_token. Vuelve a intercambiar cuando una llamada reciba 401, o poco antes de que se agote expires_in, y reintenta la llamada una vez. Si el propio intercambio falla con invalid_client o invalid_scope, el cliente o su secreto se ha eliminado, revocado o restringido: detente y corrígelo en la página Integraciones, porque reintentar no puede funcionar. Conserva el token entre llamadas: el endpoint de tokens limita los intercambios por cliente y por dirección, y un programa que intercambia en cada llamada se rechaza con 429 y rate_limited dentro de la hora (espera a Retry-After). Esta concesión no tiene token de actualización: se vuelve a intercambiar el secreto.

Los tokens de acceso solo alcanzan las rutas de la API

Un token de acceso solo funciona en rutas bajo /v1/. Si se envía a cualquier otra ruta de Lingara, se rechaza con 401, y el cuerpo empieza por api_token_not_accepted, como texto plano o dentro de un campo error, nunca en el sobre {code, error} que usan las rutas /v1/. Envía el token de acceso en la cabecera Authorization, como se muestra abajo.

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Ámbitos

Cada operación necesita exactamente un ámbito, indicado en su página. Un token de acceso sin ese ámbito se rechaza con 403 y el código insufficient_scope. Para llamar a la operación, solicita su ámbito en el intercambio, si el cliente lo tiene permitido. La tabla siguiente enumera cada ámbito y las operaciones que permite.

Quién paga una llamada

Un cliente se factura de una de dos formas, elegida al crearlo. Un cliente allowance consume la cuota de su propietario, la misma cuota que tus aplicaciones, y sus tokens de acceso también la consumen; GET /v1/usage muestra lo que queda. Un cliente metered no consume cuota: se factura por crédito mediante una suscripción de facturación por uso que configuras en la página Integraciones. Sus llamadas se rechazan con 402 y spend_cap_reached en cuanto el cliente o tu cuenta alcanza su límite de gasto mensual, y con 402 y metered_billing_inactive mientras la facturación por uso no esté activa. Un plan de lección son 10 créditos, un turno del tutor 1 crédito y una generación de vocabulario 3 créditos, así que las units que informa GET /v1/usage se convierten en créditos con esos pesos. Una llamada que una aplicación hace en nombre de otro usuario, con un token obtenido de un código de autorización, siempre consume la cuota de ese usuario, sea cual sea el modo del cliente.

Guarda los secretos y los tokens en un servidor

El secreto del cliente debe estar en un servidor que controles, nunca en una página web, una extensión del navegador o un paquete de aplicación, donde cualquiera puede leerlo. Una aplicación nativa es un cliente público y no guarda ningún secreto. Ni /v1/ ni el endpoint de tokens responden a una solicitud preliminar entre orígenes, así que un navegador en otro sitio no puede llamarlos de todos modos.

Gestionar clientes

En la página Integraciones, en app.getlingara.com/admin, crea, renombra y elimina clientes, cambia lo que puede hacer cada uno y la versión a la que está fijado, y crea y revoca sus secretos. Eliminar un cliente detiene de inmediato todos los tokens de acceso que tiene y pone fin a la autorización que cada usuario le haya concedido. Revocar un secreto detiene de inmediato todos los tokens de acceso obtenidos a cambio de ese secreto. Restringir los ámbitos de un cliente también se aplica de inmediato; ampliarlos, o cambiar su versión, se aplica a partir del siguiente intercambio.

Rotar un secreto

Un cliente puede tener dos secretos a la vez. Para rotar, crea un secreto nuevo, despliégalo y revoca el antiguo cuando su fecha de «Último uso» en la página Integraciones deje de cambiar. Un proceso que ya tiene el secreto nuevo pero aún conserva un token del antiguo recibe un único 401 y vuelve a intercambiar. El único secreto de un cliente no se puede revocar: crea antes su sustituto o elimina el cliente.

Si una traducción y la referencia en inglés difieren, prevalece la referencia en inglés.