ThunderPhone 2.0 正式上線。自助開通，每分鐘 2¢ 起。查看公告
立即開始

Connect tools & data

View as Markdown
Open in
ClaudeChatGPTCursor

使用 OAuth 連線

授權 MCP 用戶端與 ThunderPhone CLI，無須分享 API 金鑰。

OAuth 可讓應用程式以你核准的權限連線至一個 ThunderPhone 組織。目錄用戶端預設應使用 OAuth。對於需要手動設定 Bearer 權杖的用戶端，仍可使用組織 API 金鑰。

核准連線

在你的 MCP 用戶端中啟動連線。登入 ThunderPhone，確認應用程式名稱與請求的權限，選擇組織，然後選取 核准。如果不是你啟動的連線，或你不信任該應用程式，請選取 拒絕。應用程式名稱由其開發者提供，並非驗證標章。

讀取權限可存取指定資料；當請求 calls:read 時，也包括錄音與逐字稿。寫入權限可變更或刪除資源；通話、行銷活動、購買電話號碼與部署可能產生成本或影響正式環境。你的組織角色權限仍然適用。

如要透過 CLI 連線，請開啟終端機顯示的驗證連結，比對八字元代碼，選擇你的組織並核准。僅開啟連結不會授予存取權。代碼會在 15 分鐘後失效。

中斷應用程式連線

在控制台中開啟 組織 → API 金鑰 → 已授權的應用程式，然後選擇 撤銷。這會撤銷你為目前組織選取的授權，包括其存取權杖與重新整理權杖。若要再次授權，請從該應用程式重新連線。

MCP 用戶端探索

使用伺服器 URL https://api.thunderphone.com/v1/mcp。未提供有效驗證的請求會收到 401，內容如下：

WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"

擷取該文件，然後擷取位於 https://api.thunderphone.com/.well-known/oauth-authorization-server 的授權伺服器中繼資料。資源中繼資料也可從 /.well-known/oauth-protected-resource/v1/mcp 取得。請使用傳回的端點，而非自行組合端點。資源識別碼為 https://api.thunderphone.com/v1/mcp。

伺服器支援搭配 S256 PKCE 的授權碼流程、輪替更新權杖、公開動態用戶端註冊、撤銷，以及裝置授權授與。沒有用戶端密鑰或隱含授與。OpenID 探索也可從 /.well-known/openid-configuration 取得；其中包含相同的授權伺服器欄位，以及 subject_types_supported: ["public"] 和 userinfo 端點。不支援 ID 權杖與用戶端 ID 中繼資料文件（CIMD）。

註冊公開用戶端

將 JSON 傳送至 POST /v1/oauth/register：

{
  "client_name": "My MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

儲存傳回的 client_id。重新導向必須使用 HTTPS，或在 127.0.0.1 或 localhost 上使用 HTTP。註冊精確的回呼 URI，包括其連接埠與路徑。不接受片段與內嵌認證資訊。選用的 client_uri 和 logo_uri 必須使用 HTTPS；ThunderPhone 不會在註冊期間擷取它們。註冊設有速率限制。已註冊的用戶端不會到期，且連線撤銷後仍會保持註冊狀態。HTTPS 回呼包括 https://chatgpt.com/connector/oauth/<id> 與 https://chatgpt.com/connector_platform_oauth_redirect。每個連線都可以註冊自己的用戶端。

授權碼

開啟探索到的授權端點，並帶入 client_id、精確註冊的 redirect_uri、response_type=code、隨機的 state、scope、code_challenge、code_challenge_method=S256 與 resource=https://api.thunderphone.com/v1/mcp。將新的高熵 PKCE 驗證碼計算為未補齊的 base64url SHA-256 摘要，以取得挑戰值。交換授權碼前，請檢查傳回的 state 與 iss。每個授權回應都會以 iss 識別發行者，包括拒絕與通訊協定錯誤，且必須與探索到的 issuer 完全相符。無效用戶端或回呼的錯誤會在本機傳回，不會重新導向至該回呼。

使用表單編碼在 POST /v1/oauth/token 交換權杖（也接受 JSON）：

grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE verifier>
resource=https://api.thunderphone.com/v1/mcp

選用的 resource 參數可用於授權與權杖請求（包括更新與裝置交換）。省略時，會預設為探索到的 MCP 資源。提供時，必須與該資源完全相符；其他值會傳回 invalid_target。存取權杖會帶有該目標對象，而 MCP 會以 401 和探索挑戰拒絕缺少目標對象或目標對象不同的權杖。

授權請求與授權碼會在 10 分鐘後到期。每個權杖回應都包含 access_token、token_type（Bearer）、expires_in（預設為 3600 秒）、refresh_token、scope、organization_id 與 organization_name。僅透過 Authorization: Bearer 標頭傳送存取權杖。切勿將權杖放入 URL、日誌、原始碼控制或聊天內容中。

更新與撤銷

在權杖端點中使用 grant_type=refresh_token、client_id、refresh_token 與 resource 進行更新。以原子方式儲存新的更新權杖，並停止使用舊權杖。更新權杖若 30 天未成功更新即會到期。選用的 scope 可縮小已授與的權限。offline_access 一律會包含在內，且一律會簽發更新權杖。未帶有 scope 的初始請求只會授與 offline_access，因此用戶端應請求所需權限。

重複使用授權碼或已輪替的更新權杖，會撤銷整個授權。請在單一用戶端內序列化更新作業；重播已成功交換的認證資訊不是安全的重試策略。

若要中斷連線，請將 token 與 client_id 傳送至 POST /v1/oauth/revoke。撤銷任一權杖都會撤銷其授權，包括由其簽發的所有權杖。未知權杖會傳回成功，但不會透露其是否存在。控制台工作階段可透過 GET /v1/oauth/grants 列出自己的授權，並透過 DELETE /v1/oauth/grants/<id> 撤銷其中一項，使用 X-ThunderPhone-Org 選取組織。

裝置授權

裝置授權僅限預先註冊的用戶端；動態註冊的用戶端會收到 unauthorized_client。預先註冊的公開用戶端 thunderphone-cli 支援裝置授權與更新。將 client_id=thunderphone-cli 與 scope 傳送至 POST /v1/oauth/device/code。向使用者顯示 user_code 與 verification_uri，或開啟 verification_uri_complete。

使用 grant_type=urn:ietf:params:oauth:grant-type:device_code、client_id 與 device_code 輪詢權杖端點，且至少等待傳回的 interval（5 秒）。收到 authorization_pending 時繼續輪詢。收到 slow_down 時，後續每個請求都應使用回應中傳回的新 interval（增加 5 秒）。收到 access_denied、expired_token 或任何其他錯誤時停止。切勿自動核准裝置代碼。

預先註冊的 thunderphone-mcp 用戶端接受任何連接埠上的 http://127.0.0.1/callback 與 http://localhost/callback。通訊協定、主機、路徑與查詢必須相符；權杖交換必須使用授權時的精確重新導向 URI（包括連接埠）。動態註冊的用戶端需要精確比對重新導向 URI，包括連接埠。如需其他路徑，請動態註冊不同的回呼。

帳戶身分與工作區網域檢查

請將 openid email 與你的用戶端所需操作範圍一併請求。使用 Bearer 標頭中的存取權杖呼叫探索到的 userinfo_endpoint（GET /v1/oauth/userinfo）。成功回應包含：

{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}

sub 是穩定的使用者識別碼；org_id 是同意授權期間所選取的組織。此端點需要兩個身分範圍，任一缺少時會傳回 403。若帳戶沒有已驗證的電子郵件設定檔，會傳回帶有 error=access_denied 的 403，而非宣稱未驗證的電子郵件可信任。無效、已到期、已撤銷或目標對象錯誤的權杖會傳回 401。人類工作階段權杖與組織 API 金鑰無法呼叫 userinfo。不會簽發 ID 權杖。

可用權限

類別範圍
智慧體與智慧體匯入agents:read, agents:write
通話calls:read, calls:write
電話號碼、封鎖的來電者與 VoIPnumbers:read, numbers:write
知識knowledge:read, knowledge:write
活動campaigns:read, campaigns:write
整合、Webhook 端點、MCP 伺服器integrations:read, integrations:write
語音voices:read
測試情境、測試執行、驗證testing:read, testing:write
帳務billing:read
帳戶身分與已驗證的電子郵件openid、email（兩者皆為 userinfo 所需）
持續連線offline_access（一律包含）

GET、HEAD 與 OPTIONS 使用讀取範圍；其他方法使用寫入範圍。無法透過 OAuth 變更語音與帳務；POST /v1/voices/preview 使用 voices:read，因為它會預覽語音而不變更其設定。MCP 工具會強制套用其底層 REST 操作的範圍。即使授權使用者同時屬於兩個組織，跨組織移轉仍會遭到拒絕。其他 API 類別（包括 API 金鑰管理與人類帳戶設定）無法透過 OAuth 使用。REST 操作缺少權限時，會傳回含有 WWW-Authenticate: Bearer error="insufficient_scope", scope="..." 的 403。無效或過期的存取權杖會傳回 401。

MCP 工具驗證訊號

tools/list 中的每個工具都包含 securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]，其範圍為該工具 REST 操作的範圍。公開文件工具使用空白範圍清單，但仍需要已驗證的連線。

有效權杖若缺少工具所需的範圍，會收到 HTTP 200，其中 JSON-RPC result 包含 isError: true、content 中的說明文字，以及 _meta["mcp/www_authenticate"]。後者是陣列，包含帶有 resource_metadata、error="insufficient_scope"、error_description 與必要 scope 的 Bearer 挑戰。工具不會執行。使用此挑戰要求擴充同意授權。缺少或無效的驗證仍會傳回帶有 WWW-Authenticate 的 HTTP 401；REST 範圍失敗仍會傳回 HTTP 403。

憑證保留

API 每小時會在測試環境與正式環境執行 python manage.py oauth_cleanup。它會移除過期的授權要求與裝置代碼。過期的存取權杖、授權代碼及重新整理權杖雜湊，只有在其授權已撤銷或整個家族已失效後才會清除。只要該家族仍有可用的重新整理權杖、授權代碼、已核准的裝置代碼或存取權杖，已使用的雜湊就會保留，因此清理作業不會停用重播偵測。