Každý požadavek na API musí prokázat, kdo ho odesílá a ke kterým enginům dané organizace může přistupovat. Lingo.dev to řeší jedinou hlavičkou v každém požadavku: X-API-Key. Žádná výměna tokenů, žádná session, žádný OAuth kolotoč, který by bylo potřeba obcházet skripty – stejnou hlavičku připojíte jak k synchronnímu volání localize, tak k odeslání asynchronní úlohy.
Tahleta jednoduchost má i druhou stranu, kterou je dobré znát ještě před prvním voláním: klíč je vázaný na organizaci a zobrazí se jen jednou. Na téhle stránce najdete, jak tahle hlavička vypadá, kam klíč dosáhne a kam ho uložit. Co API vrací, když je hlavička chybná, najdete na stránce Chyby a stavové kódy.
Jste v API noví?
Začněte na stránce Přehled, kde najdete základní URL a mentální model enginu. Tahle stránka předpokládá, že už máte API klíč z dashboardu a potřebujete ho jen poslat.
Hlavička#
V každém požadavku posílejte svůj klíč v hlavičce X-API-Key:
X-API-Key: your_api_keyV praxi – stejná hlavička se posílá na každý endpoint, synchronní i asynchronní:
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" }
}'Správný klíč vrátí standardní odpověď daného endpointu – tady 202 s groupId. Chybějící nebo neplatná hlavička vrátí 401; tahle odpověď i ostatní kódy jsou popsané na stránce Chyby.
Kam jeden klíč dosáhne#
Klíč patří organizaci, ne jednomu konkrétnímu enginu. Jeden klíč zpřístupní každý lokalizační engine v dané organizaci, takže nemusíte vytvářet samostatné přihlašovací údaje pro každý engine – stejné X-API-Key funguje, ať cílíte na marketingový engine nebo engine pro dokumentaci, a engineId můžete vynechat, pokud chcete použít výchozí engine organizace.
Tohle široké oprávnění je praktické, ale právě to je potřeba zvážit: uniklý klíč zpřístupní všechno, k čemu má organizace přístup. Zacházejte s ním proto jako s jakýmkoli produkčním tajemstvím. Načítejte ho z proměnné prostředí nebo ze správce tajemství, nikdy ho necommitujte a držte ho na serverové straně – klíč autentizuje volání z vašeho backendu, ne z prohlížeče, kde si ho může kdokoli přečíst. Stejné pravidlo platí i pro realtime rozhraní WebSocket: autentizuje se stejným klíčem, takže i tato spojení otevírejte na serveru.
Klíče generujete a spravujete v sekci API Keys v dashboardu.
Uložíte ho jednou – nebo vůbec#
Klíč se zobrazí jen jednou, a to ve chvíli, kdy ho vytvoříte. Jakmile ten dialog zavřete, už ho nepůjde znovu zobrazit.
Než stránku opustíte, zkopírujte si klíč
API klíče se při vytvoření zobrazují pouze jednou. Jakmile se klíč objeví, hned si ho uložte do správce tajemství nebo do prostředí – později už ho nepůjde obnovit. Pokud klíč ztratíte nebo máte podezření, že unikl, vygenerujte nový v dashboardu API Keys.
Tohle je jedno z mála míst, kde nejjednodušší cesta a nejbezpečnější cesta vedou stejným směrem: správně uložit klíč hned při vytvoření je zároveň nejrychlejší postup i jediný způsob, jak zabránit tomu, aby se produkční integrace zasekla na přihlašovacím údaji, který už nikdo nedokáže znovu zobrazit.
Další kroky#
Teď už můžete autentizovat jakékoli volání. Přirozeně se k tomu hodí dvě další věci: vědět, co se vrátí při zamítnutí požadavku, a podívat se na endpointy, které tahle hlavička odemyká.
