Hoe om 'n OAuth-kliënt te skep

API-weergawe 2026-10-affable-towhee

Voordat jy “Skep kliënt” op die Integrasies-bladsy druk, besluit oor drie dinge: wat die kliënt mag doen, watter proses sy geheim hou, en wie vir sy oproepe betaal. Die Verifikasie-gids stel die reëls; hierdie bladsy pas hulle toe op twee fiktiewe maatskappye, Luba en Farducks.

Luba: die Dive Deck

Luba bedryf outonome duikbote as 'n vervoer- en saamrydiens. Sy Dive Deck wys elke passasier 'n frase van die duik op die kajuitskerm, in die taal wat hulle leer, en Luba se bedryfspan hou dop hoeveel van die toelae oor is.

Luba skep een kliënt, Luba Dive Deck, wat “Genereer woordeskat” (vocab:generate) en “Lees gebruik” (usage:read) mag doen, gefaktureer teen “Jou plan se toelae” (allowance). Twee prosesse deel dit, en elkeen vra by die inruiling slegs vir die omvang wat dit nodig het. 'n Inruiling wat scope weglaat, kry elke omvang wat die kliënt toegelaat word; een wat vra vir 'n omvang wat die kliënt nie toegelaat word nie, word in sy geheel met invalid_scope geweier, en nooit stilweg vernou nie.

Die versendingsbediener skryf elke duik se frases. Dit vra slegs vir vocab:generate, so 'n token wat daaruit uitlek, kan nie Luba se gebruik lees nie.

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

Die bedryfspaneelbord is 'n tweede bedienerkantse proses met dieselfde kliënt-ID en geheim. Dit vra slegs vir usage:read, en lees wat van die toelae oor 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"

Albei prosesse loop op Luba se bedieners. Die tablet in die kajuit vra die versendingsbediener vir frases en hou nooit die geheim of 'n token nie, want enigiets op 'n toestel wat 'n passasier kan aanraak, kan gelees word. Die Verifikasie-gids se Hou geheime en tokens op 'n bediener verduidelik hoekom.

Dieselfde kliënt as 'n projek wat jy kan kloon en laat loop: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks is 'n ketting vis-en-tjips-geriefswinkels. Terwyl 'n bestelling braai, vra die Batter Rewards-lojaliteitstoep Farducks se eie backend vir 'n kort lesplan, en lees dit dan terug. Die toep en die kasregisters roep Farducks se backend, nooit Lingara nie, so nie een van hulle hou die geheim nie.

Farducks skep een kliënt, Farducks Batter Rewards, wat “Skep lesplanne” (lesson_plans:write) en “Lees lesplanne” (lesson_plans:read) mag doen, gefaktureer teen “Jou plan se toelae” (allowance). Dit is vandag die enigste fakturering waarmee 'n kliënt geskep kan word, en 'n kliënt se fakturering word vasgelê wanneer dit geskep word. Die ander modus, metered (“Betaal per gebruik”), word onder Wie betaal vir 'n oproep in die Verifikasie-gids beskryf.

Die backend vra slegs vir lesson_plans:write en skep die plan. Die antwoord stroom, en sy started-gebeurtenis dra die plan se plan_id.

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

Stel ID op daardie plan_id, vra dan vir lesson_plans:read en lees die plan terug. Een inruiling kan vir verskeie van die kliënt se omvange vra, spasiegeskei in scope; elke opdrag hier vra vir een, want elkeen word uit 'n enkele oproep saamgestel.

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"

Eendag word die geheim in 'n ondersteuningskaartjie geplak. Op die Integrasies-bladsy druk Farducks “Nuwe geheim” en ontplooi dit na die backend, wag totdat die ou geheim se “Laas gebruik”-datum ophou verander, en druk dan “Herroep” op die ou geheim. Vanaf daardie oomblik word elke toegangtoken waarvoor die ou geheim ingeruil is, geweier. Roteer 'n geheim, in die Verifikasie-gids, gee die limiet van twee geheime en verduidelik hoekom 'n kliënt se enigste geheim nie herroep kan word nie.

Dieselfde kliënt as 'n projek wat jy kan kloon en laat loop: integrations/farducks-batter-rewards

Waarheen volgende

Die Verifikasie-gids dek die inruiling se foute, wat om te doen wanneer 'n token verval, en die rotasiereël. Die Weergawes-gids dek die weergawe waaraan 'n kliënt vasgepen is, en hoe om 'n ander een vir een oproep te kies.

Indien 'n vertaling en die Engelse verwysing verskil, is die Engelse verwysing korrek.