Bring your own key (BYOK)
Store your organization's own Anthropic, OpenAI, Google, and Mistral AI keys so localization requests run on your key and the provider bills you directly.
Bring your own model provider API key for localization. Add your organization's key on the BYOK page in Settings, then choose a model for localization. Requests for that provider's models use your key, and the provider bills you directly for the tokens. Available on the Enterprise plan.
Supported providers: Anthropic, OpenAI, Google, and Mistral AI.
Localization with your key #
Other features, such as AI reviewers and engine suggestions, do not require a provider key or model selection.
Billing #
When localization runs on your key, the provider bills you for the model's tokens, and Lingo.dev doesn't charge the model cost. The Lingo.dev infrastructure fee for localized content still applies. Localization that does not use your key pays the model cost from your Lingo.dev credits.
Who can manage keys #
Two gates control the BYOK page:
- Entitlement: the BYOK feature must be enabled for the organization (Enterprise plan). The page always appears in Settings. Without the entitlement, it says "Your own provider keys are not on your plan", and you can't save a key.
- Permission: adding, replacing, switching on or off, and removing a key need the Manage settings (
org:manage_settings) permission in the member's role. Without RBAC, every member is an Owner and has it.
Every member can see which providers have a key and whether it is in use. Keys can't be changed with an organization API key. Sign in as a person instead.
Adding a key #
- Open Settings → BYOK.
- Click Add key next to the provider.
- Paste the API key and save.
Lingo.dev checks the key with the provider when you save it. If the provider does not accept it, the key isn't saved. Check it in your provider account and paste it again.
Key visibility
A saved key is never shown again. The page only shows the last four characters and when the key was updated. To change it, use Replace and paste a new key.
Using a provider's models #
Your key is used when a localization request calls a model from that provider. To use your key in an engine's localization steps, set a model from that provider in the engine's model config.
| Situation | What happens |
|---|---|
| You have a key for the model's provider, it is on, and the provider serves the model on it | The request runs on your key |
| No key for that provider | Localization with a catalog model uses your Lingo.dev credits |
| The key is off | Localization with a catalog model uses your Lingo.dev credits |
| The model isn't in the Lingo.dev model catalog, and your key for its provider is missing or off | Localization with that model fails, because Lingo.dev's key can't serve it |
| The provider refuses the model on your key | A catalog model is retried using your Lingo.dev credits; a model beyond the catalog fails |
BYOK tag
Your key is used only when the provider serves the model under the exact ID set in your engine. Model pickers and your engine's model config tag the models your key serves with BYOK. A saved model tagged Not BYOK isn't served on your key, so localization with it uses your Lingo.dev credits. A saved model tagged Needs Mistral AI key isn't in the Lingo.dev model catalog, so it runs only on your Mistral AI key, and that key is missing or off. Add or switch on the key, or pick another model.
A missing key or a key that is off never stops localization with a catalog model.
Models beyond the catalog #
Model pickers also offer chat models that your Mistral AI key serves but the Lingo.dev model catalog doesn't have, such as mistralai/zai-glm-5-3. They're tagged BYOK and appear as provider/model, once per model under Mistral AI's own ID for it. A model saved under one of its aliases, such as mistralai/zai-glm-latest, runs on your key too.
These models run only on your key, because Lingo.dev's own key can't serve them. For now, only Mistral AI's model list says which models are chat models, so keys for other providers add no models beyond the catalog.
When your key is refused #
These failures stop the localization request. It does not retry using your Lingo.dev credits or move to the next model in the engine's model config. The error names the provider and what to fix.
| Situation | What to do |
|---|---|
| The provider rate limits your key | Retry in a few minutes, or raise the key's rate limits with the provider |
| Your provider account is out of credits or quota | Add credits or raise the quota with the provider, then retry |
| The provider rejects your key, for example because it was revoked | Replace the key on Settings → BYOK, then retry |
| Lingo.dev can't read the stored key | Save the key again on Settings → BYOK, then retry |
These are your own limits and your own account, so retrying with Lingo.dev credits would hide the problem from you.
Turning a key off #
Switch the key off to stop using it without deleting it. The page shows Off, and localization with that provider's catalog models uses your Lingo.dev credits until you switch the key back on. Models beyond the catalog don't run while the key is off.
If your plan no longer includes your own keys, a stored key shows Stored, not in use. Localization with that provider's catalog models uses your Lingo.dev credits, and models beyond the catalog don't run. The stored key is kept until you remove it.
Removing a key #
Click Remove key. The key is deleted from Lingo.dev. Localization with that provider's catalog models goes back to using your Lingo.dev credits, and models beyond the catalog stop running.
Revoke it at the provider
Removing a key from Lingo.dev does not revoke it. The key stays valid at the provider until you revoke it there.