身份驗證

API 版本 2026-10-affable-towhee

逐擺呼叫 Lingara API 攏愛紮一支存取權杖。伺服器佇權杖端點用 OAuth 用戶端的 ID 佮密鑰換一支存取權杖：這就是 OAuth 2.0 的用戶端憑證授權，是予用家己身份運作的伺服器用的。請佇 Lingara 網頁應用程式的整合頁面建立用戶端，網址是 app.getlingara.com/admin。

工作階段抑是用戶端

Lingara 應用程式用工作階段予你登入，工作階段有全部的權限範圍，會用著你方案的額度。用戶端較狹：建立的時陣由你揀伊會當用的權限範圍，伊提著的逐支存取權杖，干焦紮伊所要求的權限範圍。

三个值

用戶端 ID 用 lgr_cid_ 開頭，佇權杖端點用來認出這个用戶端。伊毋是祕密。

用戶端密鑰用 lgr_cs_ 開頭，干焦送去權杖端點。伊干焦佇建立的時陣顯示一擺：請隨複製，因為 Lingara 干焦儲存伊的雜湊值。

存取權杖用 lgr_at_ 開頭，會當用一點鐘。伊囥佇 /v1/ 下跤逐个呼叫的 Authorization: Bearer 標頭，別位攏無用。彼个標頭干焦會當囥存取權杖：若佇遐送用戶端密鑰，會予人拒絕，回傳 401。

提存取權杖

用 POST 共一份表單送去權杖端點，內底有 grant_type=client_credentials。用戶端 ID 佮密鑰會當用 HTTP Basic 驗證送，抑是當做 client_id 佮 client_secret 表單欄位送，毋過袂當兩種做伙用。scope 是用空格分開的權限範圍清單，干焦會當有這个用戶端會當用的權限範圍；若無寫，就會提著這个用戶端會當用的全部權限範圍。下跤這條指令干焦要求 usage:read，就是後壁 GET /v1/usage 範例需要的權限範圍。

curl -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"

回應內底有 access_token、token_type（Bearer）、expires_in（3600，單位是秒）佮 scope，就是這支權杖實際有的權限範圍。換無成功的時陣，會用 OAuth 錯誤格式 {error, error_description} 回應，毋是 /v1/ 的 {code, error} 封包。密鑰毋著抑是已經撤銷，抑是用戶端已經刪除，會予人拒絕，回傳 401 佮 invalid_client。要求用戶端無權要求的權限範圍，規擺換取攏會予人拒絕，回傳 400 佮 invalid_scope；權限範圍永遠袂恬恬仔予人縮狹。

替別个 Lingara 用戶做代誌

替別个 Lingara 用戶做代誌的應用程式，愛用授權碼授權。共用戶的瀏覽器送去授權網址，附 response_type=code、client_id、佮你登記過的網址完全仝款的 redirect_uri、scope、state 佮用 S256 的 code_challenge。用戶會看著 Lingara 的授權同意頁面，紲落紮 code、state 佮 iss 轉去你的 redirect_uri。用這个授權碼進前，請確認 state 是你送出去的彼个，而且 iss 是 https://api.getlingara.com。

一定愛用 PKCE

逐个用戶端攏用 PKCE，而且干焦支援 S256 方法。做一个隨機的 code_verifier，共伊的 SHA-256 雜湊值用 base64url 編碼了後，當做 code_challenge 送出，閣附 code_challenge_method=S256，彼个驗證碼愛留咧，換取的時陣愛用。無指明方法抑是用 plain 的請求，會予人拒絕，回傳 invalid_request。

換授權碼

佇 60 秒內，用 POST 共 grant_type=authorization_code、code、仝一个 redirect_uri 佮 code_verifier 送去權杖端點，閣用用戶端的身份驗證；公開用戶端干焦送 client_id。回應會加一支用 lgr_rt_ 開頭的 refresh_token。授權碼用 lgr_ac_ 開頭，干焦會當用一擺：用第二擺會予人拒絕，回傳 invalid_grant，第一擺換取發出的權杖嘛會規个失效。

更新權杖

存取權杖過期的時陣，用 POST 共 grant_type=refresh_token 佮 refresh_token 送去權杖端點，閣再用用戶端的身份驗證。逐擺更新攏會回傳一支新的更新權杖：干焦留上新的彼支。更新請一擺一擺照順序來，毋通同時做：舊的更新權杖予人取代超過 60 秒了後閣有人用，就會當做是予人偷提去，彼个安裝的權杖攏會失效，回傳 invalid_grant。更新權杖 30 工無用就會過期。權杖端點會照地址限制請求的次數，所以權杖用了才更新。

原生應用程式是公開用戶端

桌面、手機抑是命令列應用程式袂當保管密鑰，所以是公開用戶端：伊無密鑰，干焦送 client_id 去權杖端點，閣登記一个回送重新導向網址，親像 http://127.0.0.1/callback（任何連接埠），抑是一个私有 URI 配置，親像 com.example.app:/callback。用戶逐擺攏會看著授權同意頁面。網頁袂當做用戶端：權杖端點佮 /v1/ 攏袂回應跨來源預檢請求。

用戶共你的應用程式提掉的時陣

用戶隨時會當佇「已連結的應用程式」共你的應用程式提掉；若是伊家己安裝的，嘛會當直接解除安裝，了後這个應用程式下一擺呼叫就會用 401 失敗。用戶對你的應用程式登出的時陣，請佇撤銷端點撤銷伊的更新權杖，按呢彼个安裝的權杖攏會失效。

權杖過期的時陣

一點鐘了後，/v1/ 會回傳 401，代碼是 unauthorized，錯誤用 invalid_token 開頭。呼叫收著 401 的時陣，抑是 expires_in 欲用了進前，就重新換，閣共彼擺呼叫重試一擺。若換取本身用 invalid_client 抑是 invalid_scope 失敗，就是用戶端抑是伊的密鑰已經予人刪除、撤銷抑是縮狹權限範圍：請停落來，去整合頁面修理，因為重試袂成功。請佇幾若擺呼叫之間共權杖留咧：權杖端點會照用戶端佮地址限制換取的次數，逐擺呼叫攏換的程式，一點鐘內就會予人拒絕，回傳 429 佮 rate_limited（請等 Retry-After）。這種授權無更新權杖：愛閣用密鑰換。

存取權杖干焦會當用佇 API 路由

存取權杖干焦佇 /v1/ 下跤的路由有效。若送去 Lingara 別个路由，會予人拒絕，回傳 401，內容用 api_token_not_accepted 開頭，可能是純文字，嘛可能佇 error 欄位內底，永遠袂用 /v1/ 路由用的 {code, error} 封包。請像下跤按呢，佇 Authorization 標頭送存取權杖。

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

權限範圍

逐个操作拄好需要一个權限範圍，名寫佇伊的頁面。無彼个權限範圍的存取權杖會予人拒絕，回傳 403 佮代碼 insufficient_scope。欲呼叫彼个操作，請佇換取的時陣要求伊的權限範圍（前提是用戶端會當用）。下跤的表列出逐个權限範圍佮伊允准的操作。

啥人付呼叫的錢

用戶端的計費方式有兩種，佇建立的時揀好。allowance 用戶端用伊擁有者的額度，佮你的應用程式是仝一份額度，伊的存取權杖嘛用這份額度；GET /v1/usage 會顯示閣賰偌濟。metered 用戶端袂用著額度：伊是透過你佇整合頁面設定的照用量計費訂閱，照點數收費。用戶端抑是你的帳戶一下到每月的開銷上限，伊的呼叫就會用 402 佮 spend_cap_reached 拒絕；照用量計費猶未啟用的時，就會用 402 佮 metered_billing_inactive 拒絕。一份課程計畫是 10 點，一輪佮老師對話是 1 點，一擺產生詞彙是 3 點，所以 GET /v1/usage 報的 units 會當照這寡權重換算做點數。應用程式替別个用戶、用授權碼提著的權杖所做的呼叫，無論用戶端是佗一種模式，攏用彼个用戶的額度。

密鑰佮權杖愛囥佇伺服器

用戶端密鑰應該囥佇你控制的伺服器，毋通囥佇網頁、瀏覽器擴充功能抑是應用程式套件內底，佇遐逐家攏讀會著。原生應用程式是公開用戶端，無提密鑰。/v1/ 佮權杖端點攏袂回應跨來源預檢請求，所以別个網站的瀏覽器本底就呼叫袂著。

管理用戶端

佇整合頁面（網址是 app.getlingara.com/admin），你會當建立、改名佮刪除用戶端，改逐个用戶端會當做啥佮固定佇佗一个版本，閣會當建立佮撤銷伊的密鑰。刪除用戶端，伊所有的存取權杖隨就失效，所有用戶予伊的授權嘛隨結束。撤銷密鑰，用彼个密鑰換著的所有存取權杖隨就失效。縮狹用戶端的權限範圍嘛是隨就生效；放闊權限範圍抑是改版本，對下一擺換取開始生效。

輪換密鑰

一个用戶端會當仝時有兩个密鑰。欲輪換，請建立一个新密鑰閣部署，等整合頁面頂懸舊密鑰的「上尾一擺使用」日期無閣變，才撤銷舊密鑰。已經有新密鑰、毋過猶閣紮用舊密鑰換著的權杖的程序，會收著一擺 401，然後重新換。用戶端唯一的密鑰袂當撤銷：請先建立替代的密鑰，抑是共用戶端刪除。

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