Every request to the API has to prove who is asking and which organization's engines it may reach. Lingo.dev does that with one header on every request: X-API-Key. There is no token exchange, no session, no OAuth dance to script around – you attach the same header to a sync localize call and to an async job submission alike.
That simplicity has a flip side worth knowing before your first call: the key is organization-scoped and shown once. This page covers what that header looks like, what the key can reach, and where to keep it. For what the API returns when the header is wrong, see Errors and status codes.
New to the API?
Start with the Overview for the base URL and the engine mental model. This page assumes you have an API key from the dashboard and only need to send it.
The header#
Send your key in the X-API-Key header on every request:
X-API-Key: your_api_keyIn context – the same header rides every endpoint, sync or async:
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" }
}'A correct key returns the endpoint's normal response – here, a 202 with a groupId. A missing or invalid header returns 401; that response, and the rest of the codes, live on the Errors page.
What one key reaches#
A key belongs to an organization, not to a single engine. One key reaches every localization engine in that organization, so you do not mint a separate credential per engine – the same X-API-Key works whether you target your marketing engine or your docs engine, and you can leave engineId off to hit the org default.
That reach is convenient, and it is also the thing to weigh: a leaked key reaches everything the organization can. So treat it like any production secret. Load it from an environment variable or a secrets manager, never commit it, and keep it server-side – the key authenticates calls made from your backend, not from a browser where anyone can read it. The same rule covers the realtime WebSocket surface: it authenticates with the same key, so you open those connections server-side too.
Generate and manage keys in the API Keys section of the dashboard.
Stored once, or not at all#
The key is displayed a single time, at the moment you create it. After you close that dialog it cannot be retrieved.
Copy your key before you leave the page
API keys are shown only once at creation. Store the key in your secrets manager or environment the moment it appears – it cannot be recovered afterward. If a key is lost or you suspect it leaked, generate a new one in the API Keys dashboard.
This is the one place the easy path and the safe path point the same way: storing the key properly at creation is both the fastest thing to do and the only thing that keeps a production integration from getting stuck behind a credential nobody can read back.
Next steps#
You can now authenticate any call. Two things pair naturally with it: knowing what comes back when a request is rejected, and seeing the endpoints that header unlocks.
