Cada pedido à API tem de provar quem o está a fazer e a que motores da organização pode aceder. A Lingo.dev faz isso com um único cabeçalho em todos os pedidos: X-API-Key. Não há troca de tokens, nem sessão, nem uma dança de OAuth para contornar por script — anexas o mesmo cabeçalho tanto a uma chamada síncrona localize como ao envio de um job assíncrono.
Essa simplicidade tem um reverso que importa conhecer antes da primeira chamada: a chave tem âmbito ao nível da organização e é mostrada uma única vez. Esta página explica o aspeto desse cabeçalho, a que é que a chave dá acesso e onde a guardar. Para veres o que a API devolve quando o cabeçalho está incorreto, consulta Erros e códigos de estado.
Novo na API?
Começa pela Visão geral para conheceres o URL base e o modelo mental do motor. Esta página parte do princípio de que já tens uma chave de API no dashboard e só precisas de a enviar.
O cabeçalho#
Envia a tua chave no cabeçalho X-API-Key em todos os pedidos:
X-API-Key: your_api_keyEm contexto — o mesmo cabeçalho acompanha todos os endpoints, sejam 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" }
}'Uma chave válida devolve a resposta normal do endpoint — aqui, um 202 com um groupId. Se o cabeçalho estiver em falta ou for inválido, a API devolve 401; essa resposta, bem como os restantes códigos, está na página Erros.
Ao que uma única chave dá acesso#
Uma chave pertence a uma organização, não a um único motor. Uma única chave dá acesso a todos os motores de localização dessa organização, por isso não precisas de gerar uma credencial separada para cada motor — o mesmo X-API-Key funciona quer apontes para o teu motor de marketing quer para o teu motor de documentação, e podes omitir engineId para usar a predefinição da organização.
Esse alcance é prático, mas também é o ponto a ter em conta: uma chave exposta dá acesso a tudo o que a organização consegue aceder. Por isso, trata-a como qualquer segredo de produção. Carrega-a a partir de uma variável de ambiente ou de um gestor de segredos, nunca faças commit da chave e mantém-na no lado do servidor — a chave autentica chamadas feitas a partir do teu backend, não de um browser onde qualquer pessoa a pode ler. A mesma regra aplica-se à superfície em tempo real WebSocket: também autentica com a mesma chave, por isso deves abrir essas ligações igualmente no lado do servidor.
Gera e gere chaves na secção API Keys do dashboard.
Guardada uma vez — ou perdida#
A chave é mostrada uma única vez, no momento em que a crias. Depois de fechares essa caixa de diálogo, já não pode ser recuperada.
Copia a tua chave antes de saíres da página
As chaves de API só são mostradas uma vez, no momento da criação. Guarda a chave no teu gestor de segredos ou no teu ambiente assim que aparecer — depois disso, já não pode ser recuperada. Se perderes uma chave ou suspeitares que foi exposta, gera uma nova no dashboard API Keys.
Este é daqueles casos em que o caminho mais fácil e o mais seguro apontam na mesma direção: guardar corretamente a chave no momento da criação é, ao mesmo tempo, a forma mais rápida de avançar e a única maneira de evitar que uma integração de produção fique bloqueada por uma credencial que ninguém consegue voltar a consultar.
Próximos passos#
Agora já podes autenticar qualquer chamada. Há duas coisas que fazem par natural com isto: perceber o que acontece quando um pedido é rejeitado e ver os endpoints que este cabeçalho desbloqueia.
