Jede Anfrage an die API muss nachweisen, wer sie stellt und auf welche Engines einer Organisation sie zugreifen darf. Lingo.dev löst das mit genau einem Header pro Anfrage: X-API-Key. Kein Token-Austausch, keine Session, kein OAuth-Umweg, den Sie per Skript abbilden müssen – derselbe Header kommt sowohl bei einem synchronen localize-Aufruf als auch beim Absenden eines asynchronen Jobs zum Einsatz.
Diese Einfachheit hat allerdings eine wichtige Kehrseite, die Sie vor dem ersten Aufruf kennen sollten: Der Schlüssel gilt organisationsweit und wird nur einmal angezeigt. Auf dieser Seite erfahren Sie, wie der Header aussieht, worauf der Schlüssel Zugriff hat und wo Sie ihn sicher aufbewahren. Welche Antworten die API zurückgibt, wenn der Header falsch ist, lesen Sie unter Fehler und Statuscodes.
Neu bei der API?
Starten Sie mit dem Überblick für die Basis-URL und das Engine-Modell. Diese Seite setzt voraus, dass Sie bereits einen API-Schlüssel aus dem Dashboard haben und ihn jetzt nur noch mitsenden müssen.
Der Header#
Senden Sie Ihren Schlüssel bei jeder Anfrage im Header X-API-Key mit:
X-API-Key: your_api_keyIm Kontext: Derselbe Header wird bei jedem Endpunkt mitgesendet, ob synchron oder asynchron:
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" }
}'Ein gültiger Schlüssel liefert die reguläre Antwort des Endpunkts zurück – hier ein 202 mit einem groupId. Fehlt der Header oder ist er ungültig, erhalten Sie 401; diese Antwort und alle weiteren Codes finden Sie auf der Seite Fehler.
Worauf ein Schlüssel Zugriff hat#
Ein Schlüssel gehört zu einer Organisation, nicht zu einer einzelnen Engine. Ein Schlüssel erreicht jede Lokalisierungs-Engine in dieser Organisation, daher brauchen Sie keine separaten Zugangsdaten pro Engine – derselbe X-API-Key funktioniert, egal ob Sie Ihre Marketing-Engine oder Ihre Doku-Engine ansprechen. Und wenn Sie engineId weglassen, wird die Standard-Engine der Organisation verwendet.
Genau diese Reichweite ist bequem – und genau deshalb sollten Sie sie sorgfältig abwägen: Ein geleakter Schlüssel erreicht alles, worauf die Organisation zugreifen kann. Behandeln Sie ihn daher wie jedes andere Produktionsgeheimnis. Laden Sie ihn aus einer Umgebungsvariablen oder einem Secret-Manager, committen Sie ihn niemals und halten Sie ihn serverseitig – der Schlüssel authentifiziert Aufrufe aus Ihrem Backend, nicht aus einem Browser, in dem ihn jeder auslesen kann. Dasselbe gilt für die Echtzeitoberfläche WebSocket: Sie authentifiziert sich mit demselben Schlüssel, also sollten Sie auch diese Verbindungen serverseitig öffnen.
Schlüssel erstellen und verwalten Sie im Bereich API Keys des Dashboards.
Einmal gespeichert – sonst weg#
Der Schlüssel wird nur ein einziges Mal angezeigt: in dem Moment, in dem Sie ihn erstellen. Sobald Sie diesen Dialog schließen, lässt er sich nicht mehr abrufen.
Kopieren Sie Ihren Schlüssel, bevor Sie die Seite verlassen
API-Schlüssel werden bei der Erstellung nur einmal angezeigt. Speichern Sie den Schlüssel deshalb sofort in Ihrem Secret-Manager oder Ihrer Umgebung, sobald er erscheint – danach lässt er sich nicht wiederherstellen. Wenn ein Schlüssel verloren geht oder Sie vermuten, dass er offengelegt wurde, erstellen Sie im Dashboard API Keys einen neuen.
Hier zeigen der einfache Weg und der sichere Weg in dieselbe Richtung: Wenn Sie den Schlüssel direkt bei der Erstellung korrekt speichern, ist das nicht nur am schnellsten, sondern auch die einzige Möglichkeit, zu verhindern, dass eine Produktionsintegration an Zugangsdaten scheitert, die niemand mehr auslesen kann.
Nächste Schritte#
Sie können jetzt jede Anfrage authentifizieren. Zwei Themen schließen direkt daran an: was zurückkommt, wenn eine Anfrage abgelehnt wird, und welche Endpunkte dieser Header freischaltet.
