如何建立 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

下一步

驗證指南說明了換取的錯誤、權杖到期時該怎麼做，以及輪換規則。版本指南說明了用戶端固定的版本，以及如何為單次呼叫選擇另一個版本。

如譯文與英文參考文件有出入，以英文參考文件為準。