Cómo crear un cliente OAuth

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

Antes de pulsar «Crear cliente» en la página Integraciones, decide tres cosas: qué puede hacer el cliente, qué proceso guarda su secreto y quién paga sus llamadas. La guía de Autenticación establece las reglas; esta página las aplica a dos empresas ficticias, Luba y Farducks.

Luba: el Dive Deck

Luba opera submarinos autónomos como servicio de transporte y de viajes compartidos. Su Dive Deck muestra a cada pasajero una frase de la inmersión en la pantalla de la cabina, en el idioma que está aprendiendo, y el equipo de operaciones de Luba vigila cuánto queda de la cuota.

Luba crea un solo cliente, Luba Dive Deck, con permiso para «Generar vocabulario» (vocab:generate) y «Leer el uso» (usage:read), facturado a «La asignación de tu plan» (allowance). Dos procesos lo comparten, y cada uno solicita en el intercambio solo el ámbito que necesita. Un intercambio que omite scope obtiene todos los ámbitos que el cliente tiene permitidos; uno que solicita un ámbito que el cliente no tiene permitido se rechaza entero con invalid_scope, y nunca se restringe en silencio.

El servidor de despacho escribe las frases de cada inmersión. Solicita solo vocab:generate, así que un token que se filtre desde él no puede leer el uso de Luba.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

El panel de operaciones es un segundo proceso del lado del servidor con el mismo ID de cliente y el mismo secreto. Solicita solo usage:read, y lee lo que queda de la cuota.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -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" | jq -r '.access_token // error(.error)')"

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

Ambos procesos se ejecutan en los servidores de Luba. La tableta de la cabina pide las frases al servidor de despacho y nunca guarda el secreto ni un token, porque todo lo que está en un dispositivo que un pasajero puede tocar se puede leer. La sección «Guarda los secretos y los tokens en un servidor» de la guía de Autenticación explica por qué.

El mismo cliente como un proyecto que puedes clonar y ejecutar: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks es una cadena de tiendas de conveniencia de fish and chips. Mientras se fríe un pedido, la aplicación de fidelización Batter Rewards pide al backend propio de Farducks un plan de lección breve y luego lo vuelve a leer. La aplicación y las cajas llaman al backend de Farducks, nunca a Lingara, así que ninguna de las dos guarda el secreto.

Farducks crea un solo cliente, Farducks Batter Rewards, con permiso para «Crear planes de lección» (lesson_plans:write) y «Leer planes de lección» (lesson_plans:read), facturado a «La asignación de tu plan» (allowance). Es la única facturación con la que se puede crear un cliente hoy, y la facturación de un cliente queda fijada al crearlo. El otro modo, metered («Pago por uso»), se describe en la sección «Quién paga una llamada» de la guía de Autenticación.

El backend solicita solo lesson_plans:write y crea el plan. La respuesta se transmite en flujo, y su evento started lleva el plan_id del plan.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

Asigna a ID ese plan_id, luego solicita lesson_plans:read y vuelve a leer el plan. Un intercambio puede solicitar varios ámbitos del cliente, separados por espacios en scope; cada comando de aquí solicita uno, porque cada uno se compone a partir de una sola llamada.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

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

Un día el secreto se pega en un ticket de soporte. En la página Integraciones, Farducks pulsa «Nuevo secreto» y lo despliega en el backend, espera a que la fecha de «Último uso» del secreto antiguo deje de cambiar y luego pulsa «Revocar» en el secreto antiguo. Todos los tokens de acceso obtenidos a cambio del secreto antiguo se rechazan desde ese momento. La sección «Rotar un secreto» de la guía de Autenticación explica el límite de dos secretos y por qué no se puede revocar el único secreto de un cliente.

El mismo cliente como un proyecto que puedes clonar y ejecutar: integrations/farducks-batter-rewards

Próximos pasos

La guía de Autenticación cubre los errores del intercambio, qué hacer cuando caduca un token y la regla de rotación. La guía de Versiones cubre la versión a la que está fijado un cliente y cómo elegir otra para una sola llamada.

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