按怎建立 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

紲落來去佗位

身份驗證指南講換取的錯誤、權杖過期的時陣欲按怎做，閣有輪換的規則。版本指南講用戶端固定佇佗一个版本，佮按怎為單擺呼叫揀另外一个版本。

若是翻譯佮英文參考文件無仝，就以英文參考文件為準。