Autenticação
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, em uma página própria, logo após ser criada. Depois que você clicar em Já salvei, ela não poderá 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.