MaiAgent 作為 OAuth 授權伺服器

讓 Claude 等 MCP 客戶端以 OAuth 2.1（授權碼＋PKCE）連線 MaiAgent MCP：端點、應用程式註冊、Redirect URI、權杖效期與輪替，以及 scope 的實際作用

MaiAgent 內建 OAuth 2.1 授權伺服器。Claude 等 MCP 客戶端可以用 OAuth 連線 MaiAgent MCP，不必在設定檔裡貼 API Key：成員在瀏覽器登入、按下授權後，客戶端取得短效的存取權杖，以這位成員的身分操作 MaiAgent。本頁寫給兩種讀者：要讓員工在 MCP 客戶端用自己帳號連 MaiAgent 的客戶 IT，以及要讓自家服務以成員身分呼叫 MaiAgent 的開發者。

和使用者手冊的分工：後台操作見使用者手冊OAuth 應用程式；MCP 客戶端的連線設定（API Key 與 OAuth）見MaiAgent MCP。本頁只寫協定規格與整合要點。

本頁說的是 MaiAgent 核發權杖。反方向，也就是 MaiAgent 去連第三方 OAuth 服務，請見OAuth 2.0 整合與 Token 自動刷新機制。

OAuth 與 API Key 怎麼選

項目	OAuth（本頁）	API Key
代表的身分	按下授權的成員本人	金鑰綁定的成員
交付方式	成員在瀏覽器登入並同意，不必經手任何密鑰	複製金鑰貼進客戶端設定
效期	存取權杖 1 小時，由客戶端自動換新	依金鑰的到期時間，可設為永不過期
權限	等於成員角色，scope 不另外限制（見scope 的實際作用）	等於成員角色
金鑰的 RPM 限制	不適用	適用，見API 共通規範

只用 SSO 登入、沒有 MaiAgent 密碼的成員目前無法完成 OAuth 授權（見登入與同意），這類成員請改用 API Key。

端點

SaaS 的授權伺服器是 https://api.maiagent.ai。地端與私有雲部署請換成貴公司的平台網域，中繼資料裡的網址會跟著請求的網域產生。

用途	方法與路徑
授權伺服器中繼資料（RFC 8414）	GET /.well-known/oauth-authorization-server
授權	GET /o/authorize/
換發權杖	POST /o/token/
撤銷權杖（RFC 7009）	POST /o/revoke_token/

中繼資料宣告的能力如下，和實際行為一致：

欄位	值
response_types_supported	code
grant_types_supported	authorization_code、refresh_token
code_challenge_methods_supported	S256
token_endpoint_auth_methods_supported	none、client_secret_basic、client_secret_post
scopes_supported	read、write

MaiAgent 不支援動態用戶端註冊（Dynamic Client Registration），中繼資料沒有 registration_endpoint。MCP 客戶端必須能填入預先註冊的 Client ID，請先依下一節在組織裡註冊應用程式。

在組織註冊 OAuth 應用程式

在後台 組織設定 → 組織概覽 → 管理操作 → OAuth 應用程式 建立應用程式、取得 Client ID；頁面上的 連線資訊 卡片列出 Discovery、Authorize 與 Token 端點。建立步驟、誰能管理、Client Secret 的保存與重新產生，見使用者手冊OAuth 應用程式。整合時要注意：

• 應用程式類型建立後不可變更：Public 給 MCP 客戶端（如 Claude），靠 PKCE 授權，不核發 client secret；Confidential 給伺服器端整合，會核發 client secret。

• 重新產生 Client Secret 後舊 secret 立即失效，已核發的權杖不受影響；刪除應用程式後，所有透過它連線的成員，權杖立即全部失效。

• 每個組織最多 20 個 OAuth 應用程式。

• 同一套功能也有 API：/api/v1/oauth/applications/（GET、POST、PATCH、DELETE，另有 POST …/{id}/regenerate-secret/），權限規則與後台相同。

Redirect URI 規則

• 完全比對：scheme、主機、連接埠與路徑都要一致，不支援萬用字元；註冊的 URI 若帶查詢參數，授權請求也必須帶上。

• 只接受 https://。http:// 只限本機回呼：localhost、127.0.0.1、::1。

• 本機回呼的連接埠：註冊 http://127.0.0.1/… 或 http://[::1]/… 時，授權請求可以使用任意連接埠（RFC 8252）；註冊 http://localhost:<埠>/… 時，連接埠必須完全相同。本機 MCP 客戶端每次隨機挑埠時，請註冊 127.0.0.1 的形式。

• 網頁版 MCP 客戶端的回呼網址以該客戶端的文件為準，後台表單的範例是 https://claude.ai/api/mcp/auth_callback。

授權流程

MCP 客戶端連線 MaiAgent MCP（SaaS 為 https://mcp.maiagent.ai/mcp）時，整個流程如下：

1. 客戶端沒有帶憑證，MCP 伺服器回 401，WWW-Authenticate 標頭指向 https://mcp.maiagent.ai/.well-known/oauth-protected-resource/mcp。

2. 客戶端讀這份資源中繼資料（RFC 9728），authorization_servers 指向 https://api.maiagent.ai，再讀授權伺服器中繼資料。

3. 客戶端開瀏覽器到 /o/authorize/，成員登入並同意。

4. MaiAgent 把授權碼導回 Redirect URI，客戶端帶 code_verifier 到 /o/token/ 換權杖。

5. 之後每次呼叫都帶 Authorization: Bearer <access_token>。存取權杖過期或被撤銷時，MCP 伺服器回 401，客戶端用更新權杖換新。

自行實作客戶端時，授權請求與換發請求的格式如下：

GET /o/authorize/?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256&state=<STATE>

curl -X POST https://api.maiagent.ai/o/token/ \
  -d grant_type=authorization_code \
  -d code=<CODE> \
  -d redirect_uri=<REDIRECT_URI> \
  -d client_id=<CLIENT_ID> \
  -d code_verifier=<CODE_VERIFIER>

• PKCE 一律必填，Public 與 Confidential 都一樣，code_challenge_method 用 S256。

• Confidential 應用程式另外以 HTTP Basic（client_secret_basic）或表單欄位 client_secret（client_secret_post）帶 secret。

• 授權碼 300 秒內有效。

• 換發回應包含 access_token、token_type（Bearer）、expires_in（3600）、refresh_token 與 scope。

登入與同意

• 授權頁的登入畫面只提供 Email 與密碼：MaiAgent 密碼，或組織已啟用 LDAP 帳密登入時的企業密碼。畫面上沒有 SSO 登入按鈕，所以只用 SSO 登入、沒有密碼的帳號無法完成授權。

• 同意頁會顯示應用程式名稱、所屬組織，以及成員目前登入的 Email。

• 成員已經有這個應用程式的有效權杖時，重新連線會略過同意頁。

權杖代表誰、屬於哪個組織

• 權杖代表按下授權的成員，組織固定為應用程式所屬的組織，呼叫時不需要也不靠 X-Organization-Id 標頭。

• 呼叫當下，這位成員必須是該組織的有效成員。成員被停用、移出組織，或組織被刪除後，權杖立即無法使用，API 回 401。

• 存取權杖也能直接呼叫平台 REST API（Authorization: Bearer <access_token>），權限判斷和 API Key 相同。例外：AI Gateway 的 OpenAI 相容端點只接受 API Key；刪除自己的帳號這類高風險操作只接受互動登入。

權杖效期與輪替

項目	規則
授權碼	300 秒
存取權杖	3600 秒（1 小時）
更新權杖	每次使用都會輪替：回應帶一把新的更新權杖，舊的隨即作廢
輪替後重送	同一個請求因網路或併發而重送時，剛被輪替的舊更新權杖在 120 秒內仍可使用
明確撤銷	立即生效，沒有 120 秒寬限
更新權杖的效期	不要依賴固定效期。更新權杖會因撤銷、應用程式被刪除或成員被停用而失效，以權杖端點是否回 invalid_grant 為準

整合端收到 invalid_grant 時，請停止使用這把更新權杖，引導成員重新授權，不要在背景重試。撤銷與輪替的細節見更新權杖被撤銷或失效時。

撤銷的方式有三種：

誰來撤銷	做法	影響範圍
整合端	POST /o/revoke_token/，帶 token（可加 token_type_hint）與 client 認證	單一權杖
成員本人	GET /api/v1/oauth/authorized-applications/ 列出自己授權過的應用程式，DELETE /api/v1/oauth/authorized-applications/{id}/ 撤銷	這位成員給該應用程式的所有權杖
組織管理者	刪除 OAuth 應用程式	所有成員給該應用程式的所有權杖

更新權杖被撤銷或失效時

更新權杖被明確撤銷後，立即不能再換取存取權杖。整合端若繼續拿它向 POST /o/token/ 換發，會收到 HTTP 400，錯誤碼為 invalid_grant。整合端請這樣處理：

1. 收到 invalid_grant 時，停止使用這把更新權杖，引導成員重新授權，不要在背景重試。

2. 成員撤銷整個已授權的應用程式時，這位成員給該應用程式的所有權杖都會被撤銷，舊的更新權杖全部不能再用。

3. 正常輪替後，同一個請求因網路或併發而重送時，剛被輪替的舊更新權杖有 120 秒的重試寬限；這段寬限不適用於明確撤銷。

請把 invalid_grant 視為需要重新授權的訊號：不要假設明確撤銷後還有 120 秒可用，也不要依賴更新權杖的固定效期來安排重新授權。

scope 的實際作用

授權伺服器接受 read 與 write 兩個 scope；授權請求沒帶 scope 時，預設兩個都給。scope 目前不會限制任何 API：能做什麼完全由成員的角色權限決定，和這位成員登入後台或使用 API Key 時相同。要限制 MCP 客戶端能做的事，請替它的使用者設計專用角色，見使用者手冊角色權限管理。

常見問題

MCP 客戶端顯示找不到註冊端點或無法註冊？

MaiAgent 不支援動態用戶端註冊。請先在 OAuth 應用程式 建立應用程式，再把 Client ID（Confidential 另加 Client Secret）填進 MCP 客戶端的 OAuth 設定。

授權時出現 redirect_uri 不符？

Redirect URI 採完全比對。請確認 scheme、主機、連接埠、路徑和註冊值一字不差；本機客戶端若每次換埠，請改註冊 http://127.0.0.1/… 的形式。

連線一陣子之後要求重新授權？

更新權杖被撤銷、應用程式被刪除，或成員被停用時，權杖端點回 invalid_grant，客戶端只能請成員重新授權。重新產生 client secret 不會讓已核發的權杖失效。