點樣建立 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

下一步去邊

身份驗證指南講咗換取嘅錯誤、權杖過期嗰陣點做，同埋輪換規則。版本指南講咗用戶端固定喺邊個版本，同埋點樣為單次調用揀另一個版本。

如果譯本同英文參考文件有出入，以英文參考文件為準。