API keys and authentication

Authentication is a single static key per request. There is no token exchange, no request signing and no cookie. The only route that works without a key is GET /health.

Accepted header formats

Three forms are recognised. They are equivalent; use the first unless you are reusing a client that was written for a different provider.

When both Authorization and DeepL-Auth-Key are present, the Authorization header is used and the other one is ignored.

GET /v1/usage HTTP/1.1
Host: api.langapi.xyz
Authorization: Bearer la_live_xxxxxxxx

Anatomy of a key

la_live_ + 40 alphanumeric characters
la_test_ + 40 alphanumeric characters

The prefix names the mode, the remainder is random. The pattern is checked before the database is consulted: a value that does not match it is rejected immediately as unauthorized, without a lookup.

The dashboard shows the first twelve characters of each key so you can tell them apart. The remainder is never displayed again after creation.

Live keys versus test keys

The two modes behave identically at the API: same engine, same output, same rate limit, same character accounting. The mode is a label that appears in your usage reports, so that a load test on staging does not look like a production spike. There is no free simulation mode.

How failures are reported

The distinction is deliberate. key_revoked on a production host almost always means a rotation that was not fully deployed; unauthorized usually means a configuration or copy-paste mistake.

Routing happens before authentication, so a request to an unknown path returns 404 even when no key is sent, and a wrong HTTP method returns 405.

Rotating a key

1. Create a new key. Both keys are valid at the same time.
2. Roll the new key out to every service that uses the old one.
3. In the dashboard, watch the last used timestamp of the old key. It is

updated on every authenticated request.

1. When it stops advancing, revoke the old key.

Revocation is immediate and cannot be undone.

Keys belong to a team

Every key is attached to a team, and the team is the unit for everything that is metered: character quota or prepaid credit, the request rate limit, glossaries and usage records. Creating additional keys does not raise any limit; it only gives you more labels in the usage breakdown.

Handling keys safely

• Load the key from the environment or a secrets store, never from a file

checked into version control.

• Do not ship a key to a browser or a mobile app. Anyone can extract it. Put a

small proxy in your own backend and let it call the API.

• Use a la_test_ key in CI and revoke it when the pipeline is retired.
• If a key was exposed, revoke it first and investigate afterwards.