Cada solicitud a la API tiene que demostrar quién la hace y a qué motores de la organización puede acceder. Lingo.dev lo resuelve con una única cabecera en cada solicitud: X-API-Key. No hay intercambio de tokens, ni sesión, ni ninguna coreografía de OAuth que tengas que montar: adjuntas la misma cabecera tanto a una llamada síncrona a localize como al envío de un trabajo asíncrono.
Esa simplicidad tiene una contrapartida que conviene conocer antes de la primera llamada: la clave tiene alcance de organización y se muestra una sola vez. En esta página verás cómo es esa cabecera, a qué da acceso la clave y dónde guardarla. Para saber qué devuelve la API cuando la cabecera es incorrecta, consulta Errores y códigos de estado.
¿Te estrenas 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 del panel y que solo necesitas enviarla.
La cabecera#
Envía tu clave en la cabecera X-API-Key en cada solicitud:
X-API-Key: your_api_keyEn contexto: la misma cabecera se envía en todos los endpoints, 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 habitual del endpoint: aquí, un 202 con un groupId. Si la cabecera falta o no es válida, devuelve 401. Esa respuesta, y el resto de códigos, se explican en la página de Errores.
A qué da acceso una sola clave#
Una clave pertenece a una organización, no a un único motor. Una sola clave da acceso a todos los motores de localización de esa organización, así que no necesitas generar una credencial distinta para cada 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 motor predeterminado de la organización.
Ese alcance es cómodo, pero también es lo que debes tener en cuenta: una clave filtrada da acceso a todo lo que la organización puede alcanzar. Así que trátala como cualquier otro secreto de producción. Cárgala desde una variable de entorno o un gestor de secretos, no la subas nunca al repositorio y mantenla en el servidor: la clave autentica llamadas hechas desde tu backend, no desde un navegador donde cualquiera puede verla. La misma regla se aplica a la capa en tiempo real de WebSocket: se autentica con la misma clave, así que esas conexiones también deben abrirse desde el servidor.
Genera y gestiona claves en la sección API Keys del panel.
Se guarda una vez, o no se guarda#
La clave se muestra una sola vez, en el momento de crearla. Cuando cierres ese cuadro de diálogo, ya no podrás recuperarla.
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 podrás recuperarla. Si pierdes una clave o sospechas que se ha filtrado, genera una nueva en el panel de API Keys.
Este es uno de esos casos en los que el camino fácil y el seguro van en la misma dirección: guardar bien la clave en el momento de crearla es, a la vez, lo más rápido y lo único que evita que una integración en producción se 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: entender qué ocurre cuando se rechaza una solicitud y ver qué endpoints desbloquea esa cabecera.
