身份驗證

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，然後重新換過。用戶端唯一嘅密鑰係撤銷唔到嘅：請先建立替代嘅密鑰，或者刪除個用戶端。

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