Cada solicitud a la API debe demostrar quién la hace y a los motores de qué organización puede llegar. Lingo.dev lo resuelve con un encabezado en cada solicitud: X-API-Key. No hay intercambio de tokens, ni sesiones, ni una coreografía de OAuth que tengas que automatizar: adjuntas el mismo encabezado tanto a una llamada síncrona localize como al envío de un trabajo asíncrono.
Esa simplicidad tiene una contraparte que conviene entender antes de tu primera llamada: la clave tiene alcance a nivel organización y se muestra una sola vez. En esta página verás cómo se ve ese encabezado, a qué puede acceder la clave y dónde conviene guardarla. Si quieres saber qué devuelve la API cuando el encabezado es incorrecto, consulta Errores y códigos de estado.
¿Recién empiezas con la API?
Empieza por la Descripción general para conocer la URL base y el modelo mental del motor. Esta página asume que ya tienes una clave de API desde el panel y que solo necesitas enviarla.
El encabezado#
Envía tu clave en el encabezado X-API-Key en cada solicitud:
X-API-Key: your_api_keyEn contexto: el mismo encabezado acompaña a todos los endpoints, ya sean síncronos o asíncronos:
curl https://api.lingo.dev/jobs/localization \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"sourceLocale": "en",
"targetLocales": ["de", "ja"],
"data": { "greeting": "Welcome aboard" }
}'Una clave válida devuelve la respuesta normal del endpoint; aquí, un 202 con un groupId. Si el encabezado falta o no es válido, devuelve 401; esa respuesta, y el resto de los códigos, están en la página de Errores.
A qué te da acceso una sola clave#
Una clave pertenece a una organización, no a un solo motor. Una sola clave puede llegar a todos los motores de localización de esa organización, así que no necesitas generar una credencial distinta por motor: la misma X-API-Key funciona tanto si apuntas a tu motor de marketing como a tu motor de documentación, y puedes omitir engineId para usar el valor predeterminado de la organización.
Ese alcance es práctico, pero también es justo lo que debes tener en cuenta: una clave filtrada da acceso a todo lo que la organización puede alcanzar. Por eso, trátala como cualquier otro secreto de producción. Cárgala desde una variable de entorno o un gestor de secretos, nunca la subas al repositorio y mantenla del lado del servidor: la clave autentica llamadas hechas desde tu backend, no desde un navegador donde cualquiera puede verla. La misma regla aplica a la superficie en tiempo real de WebSocket: se autentica con la misma clave, así que esas conexiones también deben abrirse del lado del servidor.
Genera y administra claves en la sección API Keys del panel.
Se guarda una vez, o se pierde#
La clave se muestra una sola vez, en el momento en que la creas. Después de cerrar ese diálogo, ya no se puede recuperar.
Copia tu clave antes de salir de la página
Las claves de API solo se muestran una vez al crearlas. Guarda la clave en tu gestor de secretos o en tu entorno en cuanto aparezca; después no se puede recuperar. Si pierdes una clave o sospechas que se filtró, genera una nueva en el panel de API Keys.
Este es uno de esos casos en los que el camino fácil y el camino seguro apuntan en la misma dirección: guardar bien la clave en el momento de crearla es lo más rápido y, además, lo único que evita que una integración de producción quede bloqueada por una credencial que nadie puede volver a consultar.
Siguientes pasos#
Ahora ya puedes autenticar cualquier llamada. Hay dos temas que encajan de forma natural con esto: saber qué devuelve la API cuando rechaza una solicitud y ver qué endpoints habilita ese encabezado.
