Chaves de API

Max PrilutskiyCEO e cofundador4 min de leitura

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#

PessoalOrganização
ProprietárioO usuário que a criouNenhum — feita para automação
AutorizaçãoHerda a função RBAC do criador + permissões por engineAcesso 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 acessoA chave também perde o acessoNão é afetada; pertence à organização
PlanoQualquer planoQualquer plano; funções personalizadas e restrições exigem RBAC do Enterprise
Uso típicoDesenvolvimento local, MCP, scripts pontuaisPipelines 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:read e engine: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:

bash
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.

Próximos passos#