身份驗證

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，然後重新換。用戶端唯一个密鑰毋做得撤銷：請先建立替代个密鑰，抑係將用戶端刪除。

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