API-Authentifizierung

Authentifiziere API-Anfragen und gewähre den Zugriff, der für den jeweiligen Vorgang erforderlich ist.

Sende einen Lingo.dev-API-Schlüssel im X-API-Key-Header. Verwende https://api.lingo.dev/v2 als Basis-URL für die API-Referenzen in diesem Abschnitt.

http
GET /v2/organizations/YOUR_ORGANIZATION_ID/localization/jobs HTTP/1.1
Host: api.lingo.dev
X-API-Key: YOUR_API_KEY

Erstelle unter API-Schlüssel einen Schlüssel. Speichere ihn in der Umgebung deines Servers oder in einem Secret-Manager. Er darf nicht in Repositorys, Browser-Bundles, URLs oder Quelldokumenten enthalten sein.

Authentifizierungsnachweis auswählen #

Ein persönlicher Schlüssel nutzt die aktuelle Mitgliedschaft und die Berechtigungen der zugehörigen Person. Ein Organisationsdienstschlüssel gehört der Organisation und eignet sich für einen Dienst, der ohne manuelle Betreuung läuft. Rollen- und Ressourcenberechtigungen bestimmen seinen Zugriff. Eine enger gefasste explizite Berechtigung schränkt den Zugriff nicht ein, den seine Rolle bereits gewährt.

Die API akzeptiert auch das Sitzungszugriffstoken einer angemeldeten Person als Authorization: Bearer <access-token>. Bewerter können ihre Nutzersitzung oder ihren persönlichen Schlüssel verwenden, um Prüfungsentscheidungen zu übermitteln. Dienstschlüssel können keine menschlichen Prüfungsentscheidungen treffen, da diese Aktionen einer Person zugeordnet werden müssen.

Verwende pro Anfrage nur eine Authentifizierungsmethode. Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden.

Organisation und Engine auswählen #

Organisationsbezogene Routen enthalten orgId im Pfad. Rufe GET /v2/users/me/memberships ab, um die Organisations-IDs für eine Person oder einen persönlichen Schlüssel zu ermitteln. Verwende bei einem Dienstschlüssel die Organisation, der er gehört. Engine-IDs identifizieren die in Studio konfigurierte Engine. Mit GET /v2/organizations/:orgId/engines kannst du die zugänglichen Engines auflisten.

Um einen Lokalisierungsauftrag zu erstellen, zu starten, abzurufen oder herunterzuladen, brauchst du Zugriff auf die zugehörige Organisation und Übersetzungszugriff auf die zugehörige Engine. Für die Bereitstellung sind Berechtigungen zum Bearbeiten oder Erstellen der Engine sowie zum Erstellen der angeforderten Vorgaben erforderlich. Für die Prüfung von Übersetzungen gelten die Berechtigungen und die Weiterleitung für Bewerter.

Die Übergabe einer Organisations- oder Engine-ID gewährt keinen Zugriff. Eine Ressource außerhalb des Zugriffsbereichs der aufrufenden Person kann 404 zurückgeben. Wenn eine bekannte Ressource nicht gefunden wird, stelle daher sicher, dass sowohl die ID als auch die Berechtigungen der aufrufenden Person korrekt sind.

Zugriffsfehler diagnostizieren #

Lies neben dem HTTP-Status auch die Problemantwort. 401 weist auf einen fehlenden, ungültigen oder abgelaufenen Authentifizierungsnachweis hin. 402 weist auf eine Abrechnungs- oder Tarifbedingung hin, etwa einen Dienstschlüssel, der nach einer RBAC-Herabstufung deaktiviert wurde. 403 weist auf eine verweigerte Berechtigung oder eine erforderliche Nutzeridentität hin. Probleme mit der Engine-Konfiguration und den Kontolimits müssen jeweils gesondert behoben werden.

Bewahre die type des Problems, den Status und nicht geheime Ressourcen-IDs für die Diagnose auf. Protokolliere niemals den Authentifizierungsheader.

Schlüssel rotieren #

Erstelle einen Ersatzschlüssel, gewähre den erforderlichen Zugriff und aktualisiere das Geheimnis des Dienstes. Stelle sicher, dass sich damit ein bestehender Auftrag abrufen und ein Ergebnis herunterladen lässt, bevor du den alten Schlüssel widerrufst. Bewahre die erfassten Auftrags-IDs auf: Die Rotation von Authentifizierungsnachweisen ändert die Identität der Aufträge nicht.