跳轉到主要內容
讓使用者授權你的應用存取其 Ace Data Cloud 個人資料、服務訂閱、API Key、用量或訂單。使用標準 Authorization Code + S256 PKCE:應用開啟授權頁,使用者同意後收到一次性 code,再換取 OAuth access token。 OAuth access token 用於存取帳戶資源介面;呼叫模型 API 使用相應的 API Key。OAuth 授權不會自動建立 API Key、開通服務或增加餘額。

選擇串接方式

標準跳轉不要求 embed=studio、embed_origin 或 postMessage。Studio 元件模式由宿主建立授權頁並維護訊息橋接;第三方依本文末尾的元件協定串接,不要自行拼接這兩個參數。

端點與探索文件

應用管理介面需要帳戶登入驗證,不是匿名動態註冊(DCR)介面。MCP 服務自己的探索/註冊位址與本表中的帳戶 OAuth 端點是不同入口;連線至特定 MCP 時依該服務的文件和探索結果操作。 探索文件用於取得端點與協定能力。目前流程回傳 OAuth token,不回傳 id_token;不要僅因存在 openid scope 就依完整 OpenID Connect 登入流程處理。

權限範圍:使用目前 scope 名稱

scope 是以空格分隔、區分大小寫的權限名稱。新應用使用 profile:read、email:read、phone:read 等具體權限。

從哪裡取得可申請的權限

登入後,OAuth 應用清單介面 GET /api/v1/oauth2/applications/ 回傳 available_scopes;應用管理頁面的權限選擇器使用同一份目錄。這是一般自助應用應採用的可選範圍。 Discovery 的 scopes_supported 包含平台識別的所有權限名稱,不代表你的應用可以申請其中的每一項。 實際授權同時檢查:
  1. 權限是否允許委派給該應用類型;
  2. 權限是否已登記在這個 OAuth 應用的允許範圍內;
  3. 目前使用者是否擁有請求的權限。
未知、未登記、不允許委派或使用者不具備的權限會回傳 invalid_scope。授權碼兌換及重新整理時也會重新檢查,不會自動補齊或提升權限。

一般自助應用可選權限

以下為目前目錄(2026-10-09);串接時以 available_scopes 為準。 例如,只讀取個人資料用 profile:read;需要電子郵件再加 email:read;讀取既有 API Key 用 profile:read credentials:read。只有確實需要建立或修改 Key 時才申請 credentials:write,需要重新整理時再加 offline_access。 部分權限僅供平台核准的受信任應用使用,例如 sites:read、sites:write、platform-tokens:read;另一些權限不開放給一般第三方 OAuth 應用。用戶端類型 public/confidential 描述的是能否保管 secret,與應用是否受信任無關。自助建立應用不能自行開啟受信任權限。 account 是指定的官方帳戶管理 MCP 使用的帳戶權限選擇器,不是第三方應用的「全部權限」scope,不能與其他 scope 混用。第三方應明確列出需要的具體權限。

從舊文件遷移

舊名稱不作為相容別名接受。同步更新 OAuth 應用登記的 scopes、授權 URL 和自己的權限判斷;修改應用設定不會給已簽發 token 增加權限,需要使用者重新授權。

第 1 步:註冊 OAuth 應用

開啟 OAuth 應用管理,建立應用並填寫:
  • 名稱、描述、應用程式 Logo:顯示在授權頁面的應用程式一側。
  • 用戶端類型:純前端、行動或桌面用戶端選擇 Public;能在後端保管 secret 的服務選擇 Confidential。
  • 回呼位址:正式環境使用 HTTPS,並登記應用程式實際處理回呼的完整 URL。
  • 權限:從頁面提供的目錄中選擇實際需要的 scopes。
儲存 client_id。Confidential 用戶端將 client_secret 儲存在伺服器端,不能放到 HTML、前端建置變數或 URL 中。Public 用戶端換取 token 不使用 secret,即使註冊回應包含該欄位,也不能把它當作用戶端可以保密的憑證。 redirect_uri 在註冊、授權和換取 token 時必須完全一致,包括路徑、結尾斜線和查詢參數。每個帳號最多建立 20 個應用程式。Secret 只在建立/輪換時顯示;輪換後舊 secret 無法繼續進行需要用戶端驗證的兌換。

第 2 步:按鈕發起授權

每次點擊連線,產生新的隨機 state 與 code_verifier,計算:
將 state、verifier 和回呼位址儲存在應用程式自己的工作階段中,再用 URL 編碼後的參數開啟授權頁面:
Public 用戶端必須傳送 S256 PKCE。雖然 Discovery 仍列出 plain,Public 用戶端不能使用它。Confidential 用戶端也建議使用 S256;發起授權時使用了 PKCE,兌換時就必須提交對應 verifier。 使用者同意後回到 redirect_uri,查詢參數包含 code 和原樣返回的 state。拒絕時返回 error=access_denied、錯誤說明及 state。處理回呼前先驗證 state 與本次工作階段相符。授權碼有效期為 10 分鐘,且只能兌換一次;失敗後應重新發起連線,不要反覆重新整理舊回呼 URL。

第 3 步:換取 OAuth token

Public 用戶端直接從瀏覽器或用戶端兌換;Confidential 用戶端在自己的後端兌換。請求本文支援表單編碼,以下變數代表應用程式本次授權取得的資料:
Confidential 用戶端還需在伺服器端增加 client_secret 表單欄位。目前支援 client_secret_post,不要將 HTTP Basic 用戶端驗證當作已支援的方式。 成功回應中讀取 access_token、token_type、expires_in 和實際授予的 scope。只有請求並獲准 offline_access 才有 refresh_token。不要把 OAuth access token 當作模型 API 的 API Key,也不要把 token、verifier 或授權碼寫入日誌、分析事件或分享連結。

第 4 步:讀取使用者資訊和 API Key

先使用 OAuth access token 請求 UserInfo:
返回欄位取決於 scope:id 是使用者識別碼;profile:read 或 openid 可讀取基本資料(如 username、nickname、avatar、is_verified、date_joined、registration_method);電子郵件需要 email:read,手機號碼及地區需要 phone:read。不要依賴未授權欄位總是存在。 需要既有 API Key 且獲准 credentials:read 時,用 UserInfo 的 id 作為篩選條件:
返回列表使用 count 和 items,Key 欄位是 items[*].token,不是 data[0].value。user_id=me 不是這個介面的有效使用者 ID。多頁資料按 offset/limit 繼續讀取,不要把第一頁當作全部憑證。 根據應用程式、服務和有效狀態選擇適用的憑證,不要盲目取第一筆。列表為空不代表授權失敗;使用者可能尚未建立適用的 Key。OAuth access token 的權限控制與 API Key 自身的服務範圍、額度和到期條件是不同約束。 允許讀取 API Key 意味著第三方能夠儲存並使用它。撤銷 OAuth 請求或清除應用程式登入狀態不會使已複製的 API Key 失效;需要使用者在憑證管理中個別撤銷或輪換該 Key。

可執行的 Public / PKCE 瀏覽器範例

將下列頁面部署到你登記的 REDIRECT_URI,替換 CLIENT_ID 和回呼位址。按鈕發起標準授權,回到同一頁面後讀取個人資料和既有 Key 數量。範例不顯示、不持久化 Key;正式應用程式根據實際用途使用結果。先在獨立瀏覽器頁面驗證,再依照後面的 iframe 要求驗收。
範例的回呼和入口必須處於相同來源、同一瀏覽器分頁/iframe,才能讀取原先儲存的 sessionStorage。正式環境應用程式應在自己的工作階段方案中管理權杖,處理到期,並在收到回應後清除授權 URL 參數;頁面主介面應先渲染,網路失敗只影響連線狀態。

白標網站中的 iframe

客戶網站自行跳轉授權頁

使用標準 OAuth 參數和自己的回呼處理即可;window.location.assign() 導航目前的 iframe,父頁面保留在白標網域。無需為了圖示新增 embed=studio 或實作 Studio 訊息協定。 需要符合以下條件:
  • 應用程式頁面和回呼頁面使用 HTTPS,實際可存取,並允許白標父網域透過 iframe 嵌入;檢查雙方的 Content-Security-Policy: frame-ancestors 與 X-Frame-Options。
  • sandbox 允許頁面所需的指令碼、表單和來源/儲存能力。支援彈出式登入時還需要相應的彈出式視窗能力;優先使用 Studio 提供的 Website 元件設定。
  • 瀏覽器允許目前嵌入情境使用授權狀態所需的儲存。白標站登入狀態與 AuthFrontend 登入狀態可能不同,不應假設登入了白標站就已登入授權頁。
  • 回呼中的 token 交換服務可用,跨網域請求允許應用程式來源;DNS、CORS、HTTP 錯誤都必須顯示可重試的狀態,不能讓整個頁面停止渲染。
授權頁左側讀取 OAuth 應用程式 Logo;右側在瀏覽器可提供父來源且父網域通過已驗證網站校驗時讀取該 Site 的 favicon/logo,否則顯示預設圖示。這只決定品牌展示,不建立登入工作階段,也不會向客戶頁面提供帳戶權限。 目前限制:一般 OAuth 在 iframe 內需要重新登入時,登入完成後繼續回到授權頁的流程仍有缺口。 上線前必須分別驗收「Auth 已登入」和「Auth 未登入/已過期」。在該缺口修復並驗證前,首次登入可使用獨立頁面完成標準 OAuth,或採用下方的 Studio 元件授權;不要僅憑已登入的測試結果承諾所有 iframe 情境可用。

使用 Studio 目前帳號授權

在 Studio「設定 → 首頁 → 網站元件」開啟 OAuth,填寫 client_id 和已登記的回呼位址。網站與回呼必須使用相同 HTTPS 來源,並與 Studio 來源不同。第三方頁面需要:
  1. 向確切的父站點 origin 傳送 acedatacloud:oauth:ready,接收並校驗 acedatacloud:oauth:init。
  2. 按鈕產生 state 與 PKCE verifier,傳送 acedatacloud:oauth:authorize(state、S256 challenge);verifier 留在自己頁面內。
  3. 校驗父視窗、origin 和 state,處理 acedatacloud:oauth:result 中的 code 或 error,並依標準 token 端點兌換。 Studio 在元件區域顯示授權頁,使用者同意後以訊息回傳授權碼,應用程式不需要跳轉。未登入時回傳 login_required,拒絕時回傳 access_denied,等待逾時回傳 authorization_timeout。帳號變更會重建應用程式 iframe 並取消未完成的授權。
元件目前請求 profile:read credentials:read,不包含 offline_access。不要假設一定能收到 refresh token。embed=studio、embed_origin 由 Studio 宿主與授權頁維護,客戶頁面只需遵守訊息協定。 完整按鈕範例見 Studio 網站元件 OAuth 串接指南。

生命週期、更新與撤銷

Access token 的預設有效期為 15 天,應以每次回應的 expires_in 安排更新或重新授權;refresh token 預設 30 天,期限受服務設定影響。不要把這兩個值硬編碼為永久承諾。 獲准 offline_access 後,可呼叫:
更新會回傳新的 token,應用程式應儲存最新值。更新時會檢查應用程式是否仍有效、使用者是否可用、權限是否仍獲准。失敗時清除自己的連線狀態並重新授權。 目前 OAuth 更新實作不保證舊 refresh token 在更新後立即失效。 不要將取得新 token 當作舊 token 已被撤銷,也不要以輪替 secret 取代終止既有 token。 撤銷請求的呼叫方式是:
目前撤銷端點回傳 HTTP 200,但沒有實作已簽發 JWT 的即時失效。 應用程式應清除自己儲存的 token,不能把 200 當作所有已簽發 token 或 API Key 已失效的證明。涉及已洩漏或已複製的 API Key,應另行撤銷或輪替對應憑證。

常見錯誤與驗收

交付前至少驗證:正確回呼、拒絕、錯誤 state、過期/已使用 code、無 Key、網路失敗、token 過期、所需 scope 缺失,以及 iframe 情境下的首次登入與帳號切換。測試證據中不要儲存完整 code、token 或 API Key。

兩步驟驗證與重新授權

使用者開啟兩步驟驗證後,Ace Data Cloud 會在授權頁中完成驗證器驗證碼或一次性復原碼驗證,再交付授權碼。你的應用程式繼續使用標準 OAuth 流程,不應向使用者索取、儲存或轉送驗證器金鑰及復原碼。 使用者開啟、更換、關閉兩步驟驗證或復原帳號後,之前的帳號工作階段、更新權杖及相關平台授權權杖可能失效。收到無效工作階段或 invalid_grant 時,請重新發起使用者可見的授權流程,不要反覆使用舊授權碼,也不要嘗試繞過驗證。一般模型 API Key 的驗證方式維持不變;若懷疑帳號遭盜用,應另行檢查和撤銷受影響的 API Key。