As chaves de API autenticam requisições para a API de localização e o servidor MCP. A Lingo.dev oferece dois tipos — escolha o que melhor se encaixa em quem ou no que está chamando a API.
Dois tipos de chaves#
| Pessoal | Serviço | |
|---|---|---|
| Proprietário | O usuário que a criou | Nenhum — feita para automação |
| Autorização | Herda a função RBAC do criador + permissões por engine | Tem função própria e/ou escopo por engine |
| Se o proprietário perder acesso | A chave também perde o acesso | Não é afetada; o acesso é controlado pela própria função/escopo da chave |
| Plano | Qualquer plano | Enterprise (exige o entitlement de RBAC) |
| Uso típico | Desenvolvimento local, MCP, scripts pontuais | Pipelines de CI/CD, integrações em produção |
As chaves pessoais são o padrão. Já as chaves de serviço são um recurso no nível da organização, desvinculado de qualquer pessoa específica — ideal para credenciais que precisam continuar válidas após a saída de funcionários ou mudanças de função.
Criando uma chave#
Abra a página de Chaves de API no dashboard. Pessoal e Serviço ficam em abas separadas — a aba Serviço só aparece quando sua organização está no plano Enterprise.
Clique em Criar chave de API, dê um nome a ela (por exemplo, "MCP local", "chave de staging do Max") e copie a chave na janela de sucesso. A chave herda sua função RBAC atual e suas permissões por engine.
Visibilidade da chave
A chave de API completa é exibida apenas uma vez, no momento da criação. Copie e armazene com segurança — ela não poderá ser recuperada depois que você fechar a janela.
Chaves de serviço e RBAC#
As chaves de serviço seguem o mesmo modelo dos usuários: um usuário pode ter uma função no nível da organização (permissões amplas via Funções e Permissões) E/OU permissões por engine por ter sido adicionado a engines específicas. Uma chave de serviço funciona do mesmo jeito:
- Somente função — as permissões da função valem para toda a organização. Se ela incluir
engine:access, a chave alcança todas as engines da organização. - Sem função + escopo por engine — a chave fica restrita às engines que você marcar durante a criação. Depois, você pode atualizar a lista no botão Engines x/y ao lado da chave.
- Função + escopo por engine — as duas formas de autorização são aditivas. A permissão ampla da função prevalece se ela conceder
engine:access; caso contrário, a lista por engine é considerada. - Nenhum dos dois — a chave autentica, mas não consegue acessar nenhuma engine. É útil como placeholder enquanto você configura o escopo, mas não faz sentido em produção.
As proteções contra escalonamento se aplicam tanto na criação quanto na edição:
- A função escolhida deve pertencer à mesma organização.
- O conjunto de permissões da função deve ser um subconjunto de
engine:access— funções mais amplas (por exemplo, uma que incluaorg:manage_team) são rejeitadas. - Você só pode adicionar uma engine ao escopo da chave se já tiver acesso a essa engine.
Se o seu plano Enterprise expirar
As chaves de serviço fazem parte do entitlement de RBAC. Se esse entitlement for removido, todas as chaves de serviço da organização serão desativadas — as requisições voltarão com 403 e uma mensagem apontando para o plano, não para o escopo da engine. As chaves pessoais não são afetadas. Restaure o plano Enterprise ou faça a rotação para uma chave de API Pessoal.
Usando uma chave#
Envie a chave de API no cabeçalho X-API-Key em todas as requisições — o formato na wire é o mesmo para os dois tipos:
curl -X POST https://api.lingo.dev/process/localize \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"engineId": "eng_abc123", "sourceLocale": "en", "targetLocale": "de", "data": {"greeting": "Hello"}}'A mesma chave funciona tanto para a API de localização quanto para o servidor MCP.
Segurança#
- As chaves são armazenadas como hashes — a Lingo.dev não consegue recuperar uma chave depois da criação. Para fazer a rotação, exclua e crie outra.
- As chaves pessoais seguem, em tempo real, as permissões do criador. Se a função do criador for rebaixada ou uma permissão por engine for revogada, a chave perderá o mesmo acesso na próxima chamada.
- Uma chave pessoal cujo criador foi removido da organização continua funcionando apenas enquanto o RBAC estiver desativado (comportamento legado). No momento em que o RBAC é ativado, ela passa a ser negada — faça a rotação antes que fique órfã.
- As chaves de serviço têm sua própria autoridade. Editar a função ou o escopo na aba Serviço tem efeito imediato; excluir a chave revoga o acesso.
- Não há limite para o número de chaves por organização.
