So erstellst du einen OAuth-Client

API-Version 2026-10-affable-towhee

Bevor du auf der Seite Integrationen auf „Client erstellen“ klickst, entscheide drei Dinge: was der Client darf, welcher Prozess sein Secret hält und wer für seine Aufrufe bezahlt. Die Anleitung Authentifizierung nennt die Regeln; diese Seite wendet sie auf zwei fiktive Unternehmen an, Luba und Farducks.

Luba: das Dive Deck

Luba betreibt autonome U-Boote als Transport- und Mitfahrdienst. Sein Dive Deck zeigt jedem Fahrgast auf dem Kabinenbildschirm einen Satz aus dem Tauchgang, in der Sprache, die er lernt, und Lubas Betriebsteam behält im Blick, wie viel vom Kontingent noch übrig ist.

Luba erstellt einen Client, Luba Dive Deck, der „Vokabeln generieren“ (vocab:generate) und „Nutzung lesen“ (usage:read) darf und über „Kontingent deines Tarifs“ (allowance) abgerechnet wird. Zwei Prozesse teilen ihn sich, und jeder fordert beim Austausch nur den Scope an, den er braucht. Ein Austausch ohne scope erhält jeden Scope, der dem Client erlaubt ist; einer, der einen dem Client nicht erlaubten Scope anfordert, wird mit invalid_scope vollständig abgelehnt und nie stillschweigend eingeschränkt.

Der Dispatch-Server schreibt die Sätze jedes Tauchgangs. Er fordert nur vocab:generate an, sodass ein Token, das aus ihm entweicht, Lubas Nutzung nicht lesen kann.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

Das Betriebs-Dashboard ist ein zweiter serverseitiger Prozess mit derselben Client-ID und demselben Secret. Es fordert nur usage:read an und liest, was vom Kontingent übrig ist.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -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" | jq -r '.access_token // error(.error)')"

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

Beide Prozesse laufen auf Lubas Servern. Das Tablet in der Kabine fragt den Dispatch-Server nach Sätzen und hält nie das Secret oder ein Token, denn alles auf einem Gerät, das ein Fahrgast anfassen kann, lässt sich auslesen. Warum, erklärt der Abschnitt „Secrets und Tokens gehören auf einen Server“ in der Anleitung Authentifizierung.

Derselbe Client als Projekt zum Klonen und Ausführen: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks ist eine Kette von Fish-and-Chips-Imbissläden. Während eine Bestellung frittiert, fragt die Treue-App Batter Rewards Farducks' eigenes Backend nach einem kurzen Lektionsplan und liest ihn dann zurück. App und Kassen rufen Farducks' Backend auf, nie Lingara, sodass keine von beiden das Secret hält.

Farducks erstellt einen Client, Farducks Batter Rewards, der „Lektionspläne erstellen“ (lesson_plans:write) und „Lektionspläne lesen“ (lesson_plans:read) darf und über „Kontingent deines Tarifs“ (allowance) abgerechnet wird. Das ist derzeit die einzige Abrechnungsart, mit der sich ein Client erstellen lässt, und die Abrechnung eines Clients wird beim Erstellen festgelegt. Die andere Art, metered („Nutzungsbasiert bezahlen“), beschreibt der Abschnitt „Wer für einen Aufruf bezahlt“ in der Anleitung Authentifizierung.

Das Backend fordert nur lesson_plans:write an und erstellt den Plan. Die Antwort wird gestreamt, und ihr started-Ereignis trägt die plan_id des Plans.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

Setze ID auf diese plan_id, fordere dann lesson_plans:read an und lies den Plan zurück. Ein Austausch kann mehrere Scopes des Clients anfordern, durch Leerzeichen getrennt in scope; jeder Befehl hier fordert einen an, weil jeder aus einem einzigen Aufruf zusammengesetzt ist.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

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

Eines Tages wird das Secret in ein Support-Ticket eingefügt. Auf der Seite Integrationen klickt Farducks auf „Neues Secret“ und stellt es im Backend bereit, wartet, bis sich das Datum „Zuletzt verwendet“ des alten Secrets nicht mehr ändert, und klickt dann beim alten Secret auf „Widerrufen“. Jedes Zugriffstoken, gegen das das alte Secret eingetauscht wurde, wird ab diesem Moment abgelehnt. Der Abschnitt „Ein Secret rotieren“ in der Anleitung Authentifizierung nennt die Grenze von zwei Secrets und erklärt, warum das einzige Secret eines Clients nicht widerrufen werden kann.

Derselbe Client als Projekt zum Klonen und Ausführen: integrations/farducks-batter-rewards

Wie es weitergeht

Die Anleitung Authentifizierung behandelt die Fehler des Austauschs, was zu tun ist, wenn ein Token abläuft, und die Rotationsregel. Die Anleitung Versionen behandelt die Version, an die ein Client gebunden ist, und wie du für einen einzelnen Aufruf eine andere wählst.

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