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 | Acesso de leitura e tradução em toda a organização sem RBAC; função própria e/ou escopo por engine com RBAC |
| Se o proprietário perder acesso | A chave também perde o acesso | Não é afetada; pertence à organização |
| Plano | Qualquer plano | Qualquer plano; funções personalizadas e restrições exigem RBAC do Enterprise |
| 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 Chaves de API em Configurações. As chaves pessoais e as da organização ficam em abas separadas. Ambas estão disponíveis em todos os planos. Para criar uma chave da organização, é necessário ter a permissão Gerenciar chaves de API (org:manage_api_keys).
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#
Sem RBAC, as chaves comuns da organização têm acesso de leitura e tradução em toda a organização. O RBAC do Enterprise permite configurar permissões mais restritas:
- Somente função: as permissões da função se aplicam a toda a organização. São aceitas apenas as permissões
engine:readeengine:translate. - Sem função + escopo de engines: a chave tem acesso aos engines especificados nela.
- Função + escopo de engines: as duas formas de autorização somam permissões de acesso. O escopo não remove permissões mais amplas concedidas pela função.
- Nenhum dos dois: enquanto o RBAC estiver ativado, a chave não terá acesso a engines.
Para criar uma chave da organização, é necessário ter a permissão Gerenciar chaves de API. Atribuir ou alterar uma função, conceder acesso a engines ou definir o escopo de conteúdo também exige RBAC. A função deve pertencer à organização, e você só pode conceder acesso a engines com os quais tem permissão para traduzir. O escopo de conteúdo pode especificar glossários, vozes da marca e conjuntos de regras que você pode editar.
Antes de remover o RBAC
Se o RBAC for removido, as chaves comuns da organização voltam a ter acesso de leitura e tradução em toda a organização. As restrições de função e engine armazenadas deixam de limitar esse acesso. Se essas restrições forem necessárias, revogue as chaves ou faça a rotação delas antes de remover o RBAC. Isso se aplica às chaves de serviço comuns; credenciais para finalidades específicas, como chaves SCIM, têm requisitos de acesso próprios.
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 exige que seu criador continue sendo membro da organização. Use uma chave da organização para automações que precisam continuar funcionando após a saída de um colega.
- 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.