Authentifizierung

API-Version 2026-10-affable-towhee

Jeder Aufruf der Lingara-API trägt ein Zugriffstoken. Ein Server erhält eines, indem er die ID und das Secret eines OAuth-Clients am Token-Endpunkt eintauscht: der Client-Credentials-Grant von OAuth 2.0, für einen Server, der in eigenem Namen handelt. Erstelle Clients auf der Seite Integrationen der Lingara-Web-App unter app.getlingara.com/admin.

Eine Sitzung oder ein Client

Die Lingara-Apps melden dich mit einer Sitzung an, die jeden Scope besitzt und das Kontingent deines Plans verbraucht. Ein Client ist enger gefasst: Du wählst beim Erstellen die Scopes, die ihm erlaubt sind, und jedes Zugriffstoken, das er erhält, trägt nur die Scopes, die er anfordert.

Drei Werte

Die Client-ID beginnt mit lgr_cid_ und benennt den Client am Token-Endpunkt. Sie ist nicht geheim.

Das Client-Secret beginnt mit lgr_cs_ und wird nur an den Token-Endpunkt gesendet. Es wird nur einmal angezeigt, wenn du es erstellst: Kopiere es dann, denn Lingara speichert nur einen Hash davon.

Das Zugriffstoken beginnt mit lgr_at_ und gilt eine Stunde. Es gehört in den Authorization: Bearer-Header von Aufrufen unter /v1/ und nirgendwo sonst hin. Es ist der einzige Wert, der in diesen Header gehört: Ein dort gesendetes Client-Secret wird mit 401 abgelehnt.

Ein Zugriffstoken erhalten

Sende per POST ein Formular an den Token-Endpunkt mit grant_type=client_credentials. Übermittle Client-ID und Secret entweder per HTTP-Basic-Authentifizierung oder als Formularfelder client_id und client_secret, niemals beides. scope ist eine durch Leerzeichen getrennte Liste von Scopes, die dem Client erlaubt sind; lass es weg, um jeden Scope zu erhalten, der dem Client erlaubt ist. Der Befehl unten fordert nur usage:read an, den Scope, den das Beispiel GET /v1/usage weiter unten benötigt.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

Die Antwort enthält access_token, token_type (Bearer), expires_in (3600, in Sekunden) und scope, die Scopes, die das Token tatsächlich besitzt. Ein fehlgeschlagener Austausch antwortet im OAuth-Fehlerformat, {error, error_description}, nicht in der {code, error}-Hülle von /v1/. Ein falsches oder widerrufenes Secret oder ein gelöschter Client wird mit 401 und invalid_client abgelehnt. Ein Scope, den der Client nicht anfordern darf, lässt den gesamten Austausch mit 400 und invalid_scope scheitern; er wird nie stillschweigend eingeschränkt.

Für einen anderen Lingara-Nutzer handeln

Eine App, die für einen anderen Lingara-Nutzer handelt, verwendet den Authorization-Code-Grant. Leite den Browser des Nutzers zur Autorisierungs-URL mit response_type=code, client_id, einer redirect_uri, die exakt einer von dir registrierten entspricht, scope, state und einer S256-code_challenge. Der Nutzer sieht Lingaras Zustimmungsseite und kehrt mit code, state und iss zu deiner redirect_uri zurück. Prüfe, dass state der von dir gesendete Wert ist und dass iss gleich https://api.getlingara.com ist, bevor du den Code verwendest.

PKCE ist Pflicht

Jeder Client verwendet PKCE, ausschließlich mit der Methode S256. Erzeuge einen zufälligen code_verifier, sende seinen SHA-256-Hash, base64url-codiert, als code_challenge mit code_challenge_method=S256 und bewahre den Verifier für den Austausch auf. Eine Anfrage ohne Methode oder mit plain wird mit invalid_request abgelehnt.

Den Code eintauschen

Sende innerhalb von 60 Sekunden per POST an den Token-Endpunkt grant_type=authorization_code, code, dieselbe redirect_uri und den code_verifier und authentifiziere dich dabei als Client; ein öffentlicher Client sendet nur client_id. Die Antwort enthält zusätzlich ein refresh_token, das mit lgr_rt_ beginnt. Der Code beginnt mit lgr_ac_ und funktioniert nur einmal: Eine zweite Verwendung wird mit invalid_grant abgelehnt und beendet die Tokens, die der erste Austausch ausgestellt hat.

Erneuern

Wenn das Zugriffstoken abläuft, sende per POST an den Token-Endpunkt grant_type=refresh_token und das refresh_token und authentifiziere dich erneut als Client. Jede Erneuerung liefert ein neues Refresh-Token: Behalte nur das neueste. Führe deine Erneuerungen nacheinander aus: Ein altes Refresh-Token, das mehr als 60 Sekunden nach seiner Ersetzung verwendet wird, gilt als gestohlen und beendet die Tokens dieser Installation mit invalid_grant. Ein Refresh-Token, das 30 Tage lang nicht verwendet wird, läuft ab. Der Token-Endpunkt begrenzt Anfragen pro Adresse, also erneuere nur, wenn ein Token abgelaufen ist.

Native Apps sind öffentliche Clients

Eine Desktop-, Mobil- oder Kommandozeilen-App kann kein Secret geheim halten, daher ist sie ein öffentlicher Client: Sie hat kein Secret, sendet nur client_id an den Token-Endpunkt und registriert eine Loopback-Weiterleitung wie http://127.0.0.1/callback (beliebiger Port) oder ein privates Schema wie com.example.app:/callback. Der Nutzer sieht die Zustimmungsseite jedes Mal. Eine Webseite kann kein Client sein: Weder der Token-Endpunkt noch /v1/ beantworten einen Cross-Origin-Preflight.

Wenn der Nutzer deine App entfernt

Der Nutzer kann deine App jederzeit unter Verbundene Apps entfernen oder, falls er sie installiert hat, durch Deinstallieren, und ihr nächster Aufruf scheitert mit 401. Wenn sich der Nutzer von deiner App abmeldet, widerrufe ihr Refresh-Token am Widerrufs-Endpunkt; das beendet die Tokens dieser Installation.

Wenn das Token abläuft

Nach einer Stunde antwortet /v1/ mit 401, dem Code unauthorized und einem Fehler, der mit invalid_token beginnt. Tausche erneut, wenn ein Aufruf 401 erhält oder kurz bevor expires_in abläuft, und wiederhole den Aufruf einmal. Scheitert der Austausch selbst mit invalid_client oder invalid_scope, wurde der Client oder sein Secret gelöscht, widerrufen oder eingeschränkt: Hör auf und behebe es auf der Seite Integrationen, denn ein erneuter Versuch kann nicht gelingen. Behalte das Token zwischen Aufrufen: Der Token-Endpunkt begrenzt den Austausch pro Client und pro Adresse, und ein Programm, das bei jedem Aufruf tauscht, wird innerhalb der Stunde mit 429 und rate_limited abgelehnt (warte auf Retry-After). Dieser Grant hat kein Refresh-Token: Das Secret wird erneut eingetauscht.

Zugriffstokens erreichen nur die API-Routen

Ein Zugriffstoken funktioniert nur auf Routen unter /v1/. An eine andere Lingara-Route gesendet, wird es mit 401 abgelehnt, und der Body beginnt mit api_token_not_accepted, als Klartext oder in einem error-Feld, niemals in der {code, error}-Hülle, die die /v1/-Routen verwenden. Sende das Zugriffstoken im Authorization-Header, wie unten gezeigt.

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Scopes

Jede Operation benötigt genau einen Scope, der auf ihrer Seite genannt wird. Ein Zugriffstoken ohne diesen Scope wird mit 403 und dem Code insufficient_scope abgelehnt. Um die Operation aufzurufen, fordere ihren Scope beim Austausch an, sofern er dem Client erlaubt ist. Die Tabelle unten listet jeden Scope und die Operationen auf, die er erlaubt.

Wer für einen Aufruf bezahlt

Ein Client wird auf eine von zwei Arten abgerechnet, die beim Erstellen festgelegt wird. Ein allowance-Client verbraucht das Kontingent seines Eigentümers, dasselbe Kontingent wie deine Apps, und seine Zugriffstokens verbrauchen es ebenfalls; GET /v1/usage zeigt, was übrig ist. Ein metered-Client verbraucht kein Kontingent: Er wird pro Credit über ein Abonnement mit Nutzungsabrechnung abgerechnet, das du auf der Seite Integrationen einrichtest. Seine Aufrufe werden mit 402 und spend_cap_reached abgelehnt, sobald der Client oder dein Konto sein monatliches Ausgabenlimit erreicht, und mit 402 und metered_billing_inactive, solange die Nutzungsabrechnung nicht aktiv ist. Ein Lektionsplan kostet 10 Credits, eine Tutor-Runde 1 Credit und eine Vokabelerzeugung 3 Credits, sodass sich die units, die GET /v1/usage meldet, mit diesen Gewichten in Credits umrechnen lassen. Ein Aufruf, den eine App mit einem Token aus einem Autorisierungscode für einen anderen Nutzer tätigt, verbraucht immer das Kontingent dieses Nutzers, unabhängig vom Modus des Clients.

Secrets und Tokens gehören auf einen Server

Das Client-Secret gehört auf einen Server, den du kontrollierst, niemals in eine Webseite, eine Browsererweiterung oder ein App-Bundle, wo jeder es lesen kann. Eine native App ist ein öffentlicher Client und besitzt kein Secret. Weder /v1/ noch der Token-Endpunkt beantworten einen Cross-Origin-Preflight, sodass ein Browser auf einer anderen Website sie ohnehin nicht aufrufen kann.

Clients verwalten

Auf der Seite Integrationen unter app.getlingara.com/admin kannst du Clients erstellen, umbenennen und löschen, ändern, was jeder darf und an welche Version er gebunden ist, sowie seine Secrets erstellen und widerrufen. Das Löschen eines Clients stoppt sofort jedes Zugriffstoken, das er besitzt, und beendet die Freigabe, die jeder Nutzer ihm erteilt hat. Das Widerrufen eines Secrets stoppt sofort jedes Zugriffstoken, gegen das dieses Secret eingetauscht wurde. Das Einschränken der Scopes eines Clients gilt ebenfalls sofort; das Erweitern oder ein Versionswechsel gilt ab dem nächsten Austausch.

Ein Secret rotieren

Ein Client kann zwei Secrets gleichzeitig besitzen. Zum Rotieren erstelle ein neues Secret, stelle es bereit und widerrufe das alte, sobald sich sein Datum „Zuletzt verwendet“ auf der Seite Integrationen nicht mehr ändert. Ein Prozess, der bereits das neue Secret hat, aber noch ein Token aus dem alten besitzt, erhält ein einziges 401 und tauscht erneut. Das einzige Secret eines Clients kann nicht widerrufen werden: Erstelle zuerst seinen Ersatz oder lösche den Client.

Weichen eine Übersetzung und die englische Referenz voneinander ab, ist die englische Referenz maßgeblich.