As chaves de API autenticam pedidos à API de localização e ao servidor MCP. A Lingo.dev suporta dois tipos — escolha o que melhor se adequa a quem, ou ao que, está a chamar a API.
Dois tipos de chaves#
| Pessoal | Serviço | |
|---|---|---|
| Proprietário | O utilizador que a criou | Nenhum — destinada à automação |
| Autorização | Herda a função RBAC do criador + permissões por motor | Tem a sua própria função e/ou âmbito por motor |
| Se o proprietário perder acesso | A chave também perde acesso | Não é afetada; é controlada pela função/âmbito da própria chave |
| Plano | Qualquer plano | Enterprise (requer o direito RBAC) |
| Utilização típica | Desenvolvimento local, MCP, scripts ad hoc | Pipelines de CI/CD, integrações em produção |
As chaves pessoais são a opção predefinida. As chaves de serviço são um artefacto ao nível da organização, dissociado de qualquer pessoa em particular — exatamente o que precisa para credenciais que devem sobreviver à saída de colaboradores e a alterações de função.
Criar uma chave#
Abra a página Chaves de API no dashboard. Pessoal e Serviço estão em separadores separados — o separador Serviço só aparece quando a sua organização tem o plano Enterprise.
Clique em Criar chave de API, dê-lhe um nome (por exemplo, "MCP local", "chave de staging do Max") e copie a chave na caixa de diálogo de sucesso. A chave herda a sua função RBAC atual e as permissões por motor.
Visibilidade da chave
A chave de API completa só é mostrada uma vez, no momento da criação. Copie-a e guarde-a em segurança — não pode voltar a ser recuperada depois de fechar a caixa de diálogo.
Chaves de serviço e RBAC#
As chaves de serviço seguem o mesmo modelo dos utilizadores: um utilizador pode ter uma função ao nível da organização (permissões abrangentes através de Funções e Permissões) E/OU permissões por motor por ser adicionado a motores específicos. Uma chave de serviço funciona da mesma forma:
- Só função — as permissões da função aplicam-se a toda a organização. Se incluir
engine:access, a chave acede a todos os motores da organização. - Sem função + âmbito por motor — a chave fica restringida aos motores que selecionar durante a criação. Pode atualizar a lista mais tarde no botão Motores x/y junto à chave.
- Função + âmbito por motor — ambas as autoridades são aditivas. A permissão abrangente da função prevalece se conceder
engine:access; caso contrário, é consultada a lista por motor. - Nenhum dos dois — a chave autentica, mas não consegue aceder a nenhum motor. É útil como marcador temporário enquanto configura o âmbito, mas não faz sentido em produção.
As salvaguardas anti-elevação de privilégios aplicam-se tanto na criação como na edição:
- A função escolhida tem de pertencer à mesma organização.
- O conjunto de permissões da função tem de ser um subconjunto de
engine:access— funções mais abrangentes (por exemplo, uma que incluaorg:manage_team) são rejeitadas. - Só pode adicionar um motor ao âmbito da chave se já tiver acesso a esse motor.
Se o seu plano Enterprise expirar
As chaves de serviço fazem parte do direito RBAC. Se esse direito for removido, todas as chaves de serviço da organização são desativadas — os pedidos devolvem 403 com uma mensagem a apontar para o plano, e não para o âmbito do motor. As chaves pessoais não são afetadas. Restaure o plano Enterprise ou faça a rotação para uma chave de API Pessoal.
Usar uma chave#
Passe a chave de API no cabeçalho X-API-Key em cada pedido — o formato é o mesmo para ambos os 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 como para o servidor MCP.
Segurança#
- As chaves são armazenadas como hashes — a Lingo.dev não consegue recuperar uma chave depois de criada. Faça a rotação eliminando-a e recriando-a.
- As chaves pessoais seguem as permissões do respetivo criador em tempo real. Se a função do criador for despromovida ou se uma permissão por motor for revogada, a chave perde o mesmo acesso na chamada seguinte.
- Uma chave pessoal cujo criador foi removido da organização continua a funcionar apenas enquanto o RBAC estiver desativado (comportamento legacy). No momento em que o RBAC é ativado, o acesso é negado — faça a rotação antes de a chave ficar órfã.
- As chaves de serviço têm a sua própria autoridade. Editar a função ou o âmbito no separador Serviço produz efeito imediato; eliminar a chave revoga o acesso.
- Não existe limite para o número de chaves por organização.
