Toda requisição à API precisa comprovar quem está fazendo a chamada e quais engines da organização ela pode alcançar. O Lingo.dev faz isso com um único cabeçalho em toda requisição: X-API-Key. Não há troca de token, sessão nem dança de OAuth para contornar em script — você envia o mesmo cabeçalho tanto em uma chamada síncrona de localize quanto no envio de um job assíncrono.
Essa simplicidade tem um outro lado que vale entender antes da primeira chamada: a chave tem escopo de organização e é exibida uma única vez. Esta página mostra como esse cabeçalho funciona, o que a chave pode acessar e onde armazená-la. Para ver o que a API retorna quando o cabeçalho está incorreto, consulte Erros e códigos de status.
Novo na API?
Comece pela Visão geral para conhecer a URL base e o modelo mental do engine. Esta página parte do princípio de que você já tem uma chave de API no dashboard e só precisa enviá-la.
O cabeçalho#
Envie sua chave no cabeçalho X-API-Key em toda requisição:
X-API-Key: your_api_keyNa prática, o mesmo cabeçalho acompanha todos os endpoints, síncronos ou assíncronos:
curl https://api.lingo.dev/jobs/localization \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"sourceLocale": "en",
"targetLocales": ["de", "ja"],
"data": { "greeting": "Welcome aboard" }
}'Quando a chave está correta, a API retorna a resposta normal do endpoint — aqui, um 202 com um groupId. Se o cabeçalho estiver ausente ou for inválido, ela retorna 401; essa resposta, assim como os demais códigos, está na página de Erros.
O que uma única chave acessa#
Uma chave pertence à organização, não a um engine específico. Uma única chave acessa todo engine de localização dessa organização, então você não precisa gerar uma credencial separada para cada engine — o mesmo X-API-Key funciona tanto para seu engine de marketing quanto para seu engine de documentação, e você pode omitir engineId para usar o padrão da organização.
Esse alcance é conveniente — e também é justamente o que você precisa considerar: se uma chave vazar, ela dá acesso a tudo o que a organização alcança. Por isso, trate-a como qualquer segredo de produção. Carregue-a a partir de uma variável de ambiente ou de um gerenciador de segredos, nunca faça commit dela e mantenha-a no servidor — a chave autentica chamadas feitas pelo seu backend, não pelo navegador, onde qualquer pessoa pode lê-la. A mesma regra vale para a superfície de WebSocket em tempo real: ela se autentica com a mesma chave, então essas conexões também devem ser abertas no servidor.
Gere e gerencie chaves na seção API Keys do dashboard.
Salva uma vez — ou nunca#
A chave é exibida uma única vez, no momento em que você a cria. Depois que essa janela é fechada, ela não pode mais ser recuperada.
Copie sua chave antes de sair da página
As chaves de API são exibidas apenas uma vez na criação. Salve a chave no seu gerenciador de segredos ou no ambiente assim que ela aparecer — depois disso, não será possível recuperá-la. Se uma chave for perdida ou se houver suspeita de vazamento, gere uma nova no dashboard de API Keys.
Este é um daqueles raros casos em que o caminho mais fácil e o mais seguro são o mesmo: armazenar a chave corretamente no momento da criação é, ao mesmo tempo, a forma mais rápida de seguir em frente e a única de evitar que uma integração de produção fique bloqueada por uma credencial que ninguém consegue consultar de novo.
Próximos passos#
Agora você já pode autenticar qualquer chamada. Dois próximos passos fazem sentido aqui: entender o que volta quando uma requisição é rejeitada e ver quais endpoints esse cabeçalho libera.
