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 權杖及 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
帳戶身分及已驗證電郵openid、email（兩者均為 userinfo 所需）
持續連線offline_access（一律包括）

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

MCP 工具驗證訊號

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

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