API authentication
Authenticate API requests and grant the access required for each operation.
Send a Lingo.dev API key in the X-API-Key header. Use https://api.lingo.dev/v2 as the base URL for the API references in this section.
GET /v2/organizations/YOUR_ORGANIZATION_ID/localization/jobs HTTP/1.1
Host: api.lingo.dev
X-API-Key: YOUR_API_KEYCreate a key through API keys. Store it in your server's environment or secret manager. Keep it out of repositories, browser bundles, URLs, and source documents.
Choose a credential #
A personal key acts with its user's current membership and permissions. An organization service key belongs to the organization and suits an unattended service. Role grants and resource grants determine its access; a narrower explicit grant does not reduce access already supplied by its role.
The API also accepts a signed-in user's session access token as Authorization: Bearer <access-token>. A reviewer can use their user session or personal key to submit review decisions. Service keys cannot make human review decisions because those actions must identify a person.
Use one authentication method per request. Header names are case-insensitive.
Select the organization and engine #
Organization-scoped routes include orgId in the path. To find organization IDs for a user or personal key, read GET /v2/users/me/memberships. For a service key, use the organization that owns it. Engine IDs identify the engine configured in Studio; list accessible engines with GET /v2/organizations/:orgId/engines.
Creating, starting, reading, and downloading a localization job require access to its organization and translation access to its engine. Provisioning requires permission to edit or create the engine and to create the requested guidance. Reviewing translations uses the reviewer's permissions and routing.
Passing an organization or engine ID does not grant access. A resource outside the caller's scope can return 404, so confirm both the ID and the caller's permissions when a known resource cannot be found.
Diagnose an access failure #
Read the problem response as well as its HTTP status. A 401 indicates a missing, invalid, or expired credential. A 402 identifies a billing or plan condition, including a service key disabled after an RBAC downgrade. A 403 identifies refused permission or a required user identity. Engine configuration and account limits require their own corrections.
Retain the problem type, status, and non-secret resource IDs for diagnosis. Never log the authentication header.
Rotate a key #
Create the replacement, grant the required access, and update the service's secret. Verify that it can retrieve an existing job and download a result before revoking the old key. Keep recorded job IDs: rotating credentials does not change their identities.