ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Connect tools & data

使用 OAuth 連接

授權 MCP 用戶端及 ThunderPhone CLI,無需分享 API 金鑰。

OAuth 讓應用程式可在你批准的權限範圍內,連接至一個 ThunderPhone 組織。目錄客戶端預設應使用 OAuth。對於需要手動設定 Bearer 權杖的客戶端,組織 API 金鑰仍然可用。

批准連接

在你的 MCP 客戶端開始連接。登入 ThunderPhone,檢查應用程式名稱及所要求的權限,選擇一個組織,然後選取 批准。如果並非由你開始連接,或你不信任該應用程式,請選取 拒絕。應用程式名稱由其開發者提供,並非驗證標誌。

讀取權限會開放指定資料,包括在要求 calls:read 時的錄音及逐字稿。寫入權限可以變更或刪除資源;通話、活動、購買電話號碼及部署均可能產生成本或影響正式環境。你的組織角色仍然適用。

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

中斷應用程式連接

開啟 設定 → 安全性 → 你已連接的應用程式,然後在該應用程式旁選擇 中斷連接。此操作會撤銷你對目前組織的授權,包括其存取權杖及重新整理權杖。如要再次授權,請從該應用程式重新連接。

更改或重設密碼,或更改帳戶電郵地址,將會在所有位置登出你的帳戶:此操作亦會撤銷你在每個組織中授權的所有應用程式,包括 MCP 連接器、Zapier 和 CLI。其後請重新連接每個應用程式。

應用程式建立的 Webhook 端點在其存取權被撤銷後,仍會持續傳送事件,直至你將其刪除。懷疑帳戶被盜用後,請使用管理員 API 金鑰透過 GET /v1/developer/webhook-endpoints 列出端點,並刪除所有你無法辨識的端點;控制台會在 整合 → Webhooks 下列出所有端點,包括智能體本身建立的端點。

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 權杖及 Client ID Metadata Documents(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 不會在註冊期間擷取這些 URI。註冊設有速率限制。已註冊的用戶端不會過期,並會在連線被撤銷後維持註冊狀態。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 驗證器計算為 SHA-256 摘要,再以不含填充字元的 base64url 編碼,所得結果即為 challenge。在交換授權碼前,檢查回傳的 state 及 iss。每個授權回應,包括拒絕及通訊協定錯誤,均會以 iss 識別發行者,並與已探索的 issuer 完全一致。無效用戶端或回調的錯誤會在本機回傳,不會重新導向至該回調。

使用表單編碼(亦接受 JSON)在 POST /v1/oauth/token 交換:

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。如帳戶沒有已驗證的電郵設定檔,會以 403 及 error=access_denied 回應,而不會斷言未驗證電郵值得信任。無效、過期、已撤銷或受眾錯誤的權杖會回傳 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
組織設定(僅限 MCP 工具)org:read, org:write
帳戶身分及已驗證電郵openid, email(兩者均為 userinfo 所必需)
持續連線offline_access(一律包含)

GET、HEAD 及 OPTIONS 使用讀取範圍;其他方法使用寫入範圍。語音及帳單的變更操作無法透過 OAuth 執行;以下三個 POST 不會作出任何變更,並使用讀取範圍:POST /v1/voices/preview(voices:read)預覽語音,POST /v1/knowledge/.../search(knowledge:read)查詢知識庫,而 POST /v1/calls/bulk-delete/preview(calls:read)計算刪除該些通話時同時會移除的項目。MCP 工具會強制執行其底層 REST 操作的範圍;沒有單一 REST 操作的 MCP 工具會指定自己的範圍(例如 get_org_settings 使用 org:read,unblock_callers 使用 numbers:write)。org:read 及 org:write 不會開放任何 REST 路由。即使授權使用者同時屬於兩個組織,跨組織轉移仍會被拒絕。其他 API 類別,包括 API 金鑰管理及個人帳戶設定,均無法透過 OAuth 使用。REST 操作缺少所需權限時,會傳回 403,並附帶 WWW-Authenticate: Bearer error="insufficient_scope", scope="..."。無效或已過期的存取權杖會傳回 401。

MCP 工具驗證訊號

tools/list 中每個工具均包含 securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}],並附有該工具 REST 操作的範圍。公開文件工具、get_supported_languages、get_agent_capabilities、escalate_to_human 及 request_feature 使用空白範圍清單,但仍需要已驗證的連線。

有效權杖如缺少工具所需範圍,會收到 HTTP 200 及包含 isError: true 的 JSON-RPC result,並在 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。它會移除過期的授權請求及裝置代碼。過期的存取權杖、授權代碼及重新整理權杖雜湊,只有在其授權已被撤銷或整個憑證家族已失效後才會清除。只要憑證家族仍有可用的重新整理權杖、授權代碼、已批准的裝置代碼或存取權杖,已使用的雜湊便會保留,確保清理程序不會停用重播偵測。