Een OAuth-client aanmaken

API-versie 2026-10-affable-towhee

Beslis drie dingen voordat je op de pagina Integraties op 'Client aanmaken' drukt: wat de client mag, welk proces zijn geheim bewaart en wie voor zijn aanroepen betaalt. De handleiding Authenticatie legt de regels vast; deze pagina past ze toe op twee fictieve bedrijven, Luba en Farducks.

Luba: het Dive Deck

Luba exploiteert autonome onderzeeërs als vervoers- en deelritdienst. Zijn Dive Deck toont elke passagier op het cabinescherm een zin uit de duik, in de taal die hij leert, en het operationele team van Luba houdt bij hoeveel er van het tegoed over is.

Luba maakt één client aan, Luba Dive Deck, die 'Woordenschat genereren' (vocab:generate) en 'Gebruik lezen' (usage:read) mag en wordt afgerekend via 'De bundel van je abonnement' (allowance). Twee processen delen hem, en elk vraagt bij de inruil alleen de scope die het nodig heeft. Een inruil zonder scope krijgt elke scope die de client mag; een inruil die om een scope vraagt die de client niet mag, wordt in zijn geheel geweigerd met invalid_scope, en nooit stilletjes ingeperkt.

De dispatchserver schrijft de zinnen van elke duik. Hij vraagt alleen om vocab:generate, zodat een token dat daaruit uitlekt het gebruik van Luba niet kan lezen.

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}'

Het operationele dashboard is een tweede proces aan de serverkant met dezelfde client-ID en hetzelfde geheim. Het vraagt alleen om usage:read, en leest wat er van het tegoed over is.

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 processen draaien op de servers van Luba. De tablet in de cabine vraagt de dispatchserver om zinnen en bewaart nooit het geheim of een token, want alles op een apparaat dat een passagier kan aanraken, kan worden uitgelezen. De sectie 'Bewaar geheimen en tokens op een server' in de handleiding Authenticatie legt uit waarom.

Dezelfde client als project dat je kunt klonen en uitvoeren: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks is een keten van fish-and-chips-gemakswinkels. Terwijl een bestelling frituurt, vraagt de loyaliteitsapp Batter Rewards de eigen backend van Farducks om een kort lesplan en leest het daarna terug. De app en de kassa's roepen de backend van Farducks aan, nooit Lingara, zodat geen van beide het geheim bewaart.

Farducks maakt één client aan, Farducks Batter Rewards, die 'Lesplannen maken' (lesson_plans:write) en 'Lesplannen lezen' (lesson_plans:read) mag en wordt afgerekend via 'De bundel van je abonnement' (allowance). Dat is vandaag de enige afrekening waarmee een client kan worden aangemaakt, en de afrekening van een client ligt vast zodra hij is aangemaakt. De andere modus, metered ('Betalen per gebruik'), wordt beschreven in de sectie 'Wie betaalt voor een aanroep' van de handleiding Authenticatie.

De backend vraagt alleen om lesson_plans:write en maakt het plan aan. Het antwoord wordt gestreamd, en het started-event ervan bevat de plan_id van het plan.

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}'

Zet ID op die plan_id, vraag dan om lesson_plans:read en lees het plan terug. Eén inruil kan om meerdere scopes van de client vragen, gescheiden door spaties in scope; elk commando hier vraagt er één, omdat elk uit één aanroep is opgebouwd.

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"

Op een dag wordt het geheim in een supportticket geplakt. Op de pagina Integraties drukt Farducks op 'Nieuw geheim' en rolt het uit naar de backend, wacht tot de datum 'Laatst gebruikt' van het oude geheim niet meer verandert en drukt dan bij het oude geheim op 'Intrekken'. Elk toegangstoken waarvoor het oude geheim is ingeruild, wordt vanaf dat moment geweigerd. De sectie 'Een geheim roteren' in de handleiding Authenticatie noemt de limiet van twee geheimen en legt uit waarom het enige geheim van een client niet kan worden ingetrokken.

Dezelfde client als project dat je kunt klonen en uitvoeren: integrations/farducks-batter-rewards

Hoe verder

De handleiding Authenticatie behandelt de fouten van de inruil, wat je doet als een token verloopt en de rotatieregel. De handleiding Versies behandelt de versie waarop een client is vastgezet, en hoe je voor één aanroep een andere kiest.

Als een vertaling afwijkt van de Engelse referentie, is de Engelse referentie juist.