Chaves de API
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 | Organizaçã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 da organizaçã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 mesmo 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 em Configurações. As chaves Pessoais e da Organização ficam em abas separadas; a aba Organização está disponível com o plano Enterprise.
Clique em Nova chave pessoal, dê um nome a ela (por exemplo, "MCP local", "chave de staging do Max") e copie a chave quando ela aparecer. A chave herda sua função atual de RBAC e as 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 da organização e RBAC#
As chaves da organizaçã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 da organização funciona da mesma forma:
- 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 de engine — a chave fica restrita às engines que você marcar durante a criação. Depois, você pode atualizar a lista de engines editando a 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 da organização fazem parte do direito de uso de RBAC. Se esse direito for removido, todas as chaves da organização serão desativadas — as solicitações voltarão com 403 e uma mensagem apontando para o plano, não para o escopo de engine. As chaves pessoais não são afetadas. Basta restaurar o plano Enterprise ou fazer 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 da organização têm autoridade própria. Editar a função ou o escopo entra em vigor imediatamente; excluir a chave revoga esse acesso.
- Não há limite para o número de chaves por organização.