驗證

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 使用者操作的應用程式使用授權碼授權。將使用者的瀏覽器導向授權 URL，並附上 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，然後重新換取。用戶端唯一的密鑰無法撤銷：請先建立替代的密鑰，或是刪除該用戶端。

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