Chaves de API
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 | Organizaçã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 da organização são um recurso ao nível da organização, desvinculado de qualquer pessoa específica — ideal para credenciais que devem continuar válidas após a saída de colaboradores e resistir a alterações de função.
Criar uma chave#
Abra a página API keys em Settings. As chaves Pessoais e da Organização estão em separadores distintos; o separador Organização requer o plano Enterprise.
Clique em New personal key, dê-lhe um nome (por exemplo, "MCP local", "chave de staging do Max") e copie a chave quando ela for apresentada. 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 da organização e RBAC#
As chaves da organizaçã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 Roles & Permissions) E/OU permissões por motor atribuídas por ter sido adicionado a motores específicos. Uma chave da organizaçã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 de motores mais tarde, editando a 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 da organização estão incluídas na autorização RBAC. Se essa autorização for removida, todas as chaves da organização ficam desativadas — os pedidos devolvem 403 e uma mensagem a indicar o plano, não o âmbito por motor. As chaves pessoais não são afetadas. Reponha 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 da organização têm a sua própria autoridade. Editar a função ou o âmbito produz efeito imediato; eliminar a chave revoga-a.
- Não existe limite para o número de chaves por organização.