仰般建立 OAuth 用戶端

API 版本 2026-10-affable-towhee

在整合頁面撳「建立用戶端」之前，先決定三件事：用戶端做得做麼个、哪隻程序放佢个密鑰，還有麼人付佢呼叫个錢。身份驗證指南講明規則；這頁將這兜規則用在兩間虛構个公司 Luba 㧯 Farducks。

Luba：Dive Deck

Luba 經營自動駕駛个潛水艇，做運輸㧯共乘服務。佢个 Dive Deck 會在艙肚个螢幕，為每一位乘客顯示這擺潛水个一句短語，用个係乘客當在學个語言；Luba 个營運團隊就看額度還賸幾多。

Luba 建立一隻用戶端 Luba Dive Deck，分佢做得「產生詞彙」（vocab:generate）㧯「讀取使用量」（usage:read），計費方式係「你方案包含个額度」（allowance）。兩隻程序共用這隻用戶端，每隻在換取个時節淨要求自家愛用个權限範圍。無寫 scope 个換取，會拿到這隻用戶端做得用个全部權限範圍；要求用戶端毋做得用个權限範圍，歸擺換取都會分人拒絕，轉 invalid_scope，權限範圍永遠毋會靜靜仔分人縮狹。

調度伺服器負責寫每擺潛水个短語。佢淨要求 vocab:generate，所以就算從佢該位洩漏出去个權杖，也讀毋到 Luba 个用量。

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

營運儀表板係第二隻伺服器端个程序，用共樣个用戶端 ID 㧯密鑰。佢淨要求 usage:read，用來讀額度還賸幾多。

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"

兩隻程序都在 Luba 个伺服器頂高運作。艙肚个平板電腦向調度伺服器討短語，永遠毋會放密鑰抑係權杖，因為乘客摸得到个裝置頂高，麼个都讀得到。身份驗證指南裡肚个「密鑰㧯權杖愛放在伺服器」有講原因。

同一個用戶端，做得複製來執行个專案： integrations/luba-dive-deck

Farducks：Batter Rewards

Farducks 係一間炸魚㧯薯條个便利商店連鎖。訂單在炸个時節，Batter Rewards 會員應用程式會向 Farducks 自家个後端討一份短个課程計畫，再將佢讀轉來。應用程式㧯收銀機呼叫个係 Farducks 个後端，永遠毋係 Lingara，所以兩隻都無放密鑰。

Farducks 建立一隻用戶端 Farducks Batter Rewards，分佢做得「建立課程計畫」（lesson_plans:write）㧯「讀取課程計畫」（lesson_plans:read），計費方式係「你方案包含个額度」（allowance）。這係這下建立用戶端唯一做得用个計費方式，而且用戶端个計費方式在建立个時節就固定了。另一種方式 metered（「照使用量付費」）在身份驗證指南个「麼人付呼叫个錢」有說明。

後端淨要求 lesson_plans:write，再建立課程計畫。回應係串流个，裡肚个 started 事件帶等這份計畫个 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}'

將 ID 設做該隻 plan_id，然後要求 lesson_plans:read，將計畫讀轉來。一擺換取做得要求用戶端个幾下隻權限範圍，在 scope 裡肚用空格分開；這位个每條指令淨要求一隻，因為每條都係由單一擺呼叫組成个。

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"

有一日，密鑰分人貼入一張支援工單。Farducks 在整合頁面撳「新密鑰」，將佢部署去後端，等舊密鑰个「最後使用」日期無再變，正在舊密鑰撳「撤銷」。從該下開始，用舊密鑰換到个每一隻存取權杖都會分人拒絕。身份驗證指南裡肚个「輪換密鑰」有講最多兩隻密鑰个限制，㧯用戶端唯一个密鑰做麼个毋做得撤銷。

同一個用戶端，做得複製來執行个專案： integrations/farducks-batter-rewards

接下來去哪位

身份驗證指南講換取个錯誤、權杖過期个時節愛仰般做，還有輪換个規則。版本指南講用戶端固定在哪隻版本，㧯仰般為單擺呼叫揀另一個版本。

假使翻譯㧯英文參考文件無共樣，就以英文參考文件為準。