Open in

OAuth से कनेक्ट करें

API key शेयर किए बिना MCP क्लाइंट्स और ThunderPhone CLI को ऑथराइज़ करें।

OAuth किसी ऐप को आपके द्वारा मंज़ूर की गई परमिशन के साथ एक ThunderPhone संगठन से कनेक्ट करने देता है। डायरेक्टरी क्लाइंट को डिफ़ॉल्ट रूप से OAuth का उपयोग करना चाहिए। जिन क्लाइंट को मैन्युअली कॉन्फ़िगर किए गए बेयरर टोकन की आवश्यकता होती है, उनके लिए संगठन API keys उपलब्ध रहती हैं।

कनेक्शन मंज़ूर करें

अपने MCP क्लाइंट में कनेक्शन शुरू करें। ThunderPhone में साइन इन करें, ऐप का नाम और मांगी गई परमिशन जांचें, एक संगठन चुनें, और मंज़ूर करें चुनें। अगर आपने कनेक्शन शुरू नहीं किया है या आपको ऐप पर भरोसा नहीं है, तो अस्वीकार करें चुनें। ऐप के नाम उनके डेवलपर देते हैं और वे सत्यापन बैज नहीं होते हैं।

रीड परमिशन नामित डेटा को एक्सेस देती हैं, जिसमें calls:read का अनुरोध किए जाने पर रिकॉर्डिंग और ट्रांसक्रिप्ट शामिल हैं। राइट परमिशन रिसोर्स को बदल या हटा सकती हैं; कॉल, कैंपेन, फ़ोन खरीद और डिप्लॉयमेंट की लागत आ सकती है या वे प्रोडक्शन को प्रभावित कर सकते हैं। आपकी संगठन भूमिका फिर भी लागू रहती है।

CLI कनेक्शन के लिए, अपने टर्मिनल में दिखाया गया सत्यापन लिंक खोलें, आठ-वर्णों वाले कोड की तुलना करें, अपना संगठन चुनें, और मंज़ूर करें। केवल लिंक खोलने से एक्सेस नहीं मिलती। कोड 15 मिनट बाद समाप्त हो जाते हैं।

किसी ऐप को डिस्कनेक्ट करें

डैशबोर्ड में संगठन → API keys → अधिकृत ऐप्स खोलें और रद्द करें चुनें। इससे मौजूदा संगठन के लिए आपका चुना गया ऑथराइज़ेशन रद्द हो जाता है, जिसमें उसके एक्सेस और रीफ़्रेश टोकन शामिल हैं। अगर आप ऐप को फिर से ऑथराइज़ करना चाहते हैं, तो ऐप से दोबारा कनेक्ट करें।

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) समर्थित नहीं हैं।

एक सार्वजनिक क्लाइंट रजिस्टर करें

POST /v1/oauth/register पर JSON भेजें:

{
  "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 की जाँच करें। अस्वीकृति और प्रोटोकॉल एरर सहित हर ऑथराइज़ेशन रिस्पॉन्स, डिस्कवर किए गए issuer से सटीक रूप से मेल खाने वाले iss के साथ इशूअर को पहचानता है। अमान्य क्लाइंट या कॉलबैक के एरर उस कॉलबैक पर रीडायरेक्ट किए बिना लोकल रूप से लौटाए जाते हैं।

फॉर्म एन्कोडिंग का उपयोग करके 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 हेडर के माध्यम से भेजें। टोकन को कभी भी URLs, लॉग्स, सोर्स कंट्रोल या चैट में न रखें।

रिफ़्रेश और रिवोक

टोकन एंडपॉइंट पर grant_type=refresh_token, client_id, refresh_token, और resource के साथ रिफ़्रेश करें। नए रिफ़्रेश टोकन को एटॉमिक रूप से सेव करें और पुराने टोकन का उपयोग बंद करें। सफल रिफ़्रेश के बिना रिफ़्रेश टोकन 30 दिनों के बाद समाप्त हो जाते हैं। वैकल्पिक scope दी गई परमिशन को सीमित कर सकता है। offline_access हमेशा शामिल होता है और रिफ़्रेश टोकन हमेशा जारी किए जाते हैं। scope के बिना शुरुआती अनुरोध केवल offline_access देता है, इसलिए क्लाइंट्स को अपनी आवश्यक परमिशन का अनुरोध करना चाहिए।

कोड के पुन: उपयोग और रोटेट किए गए रिफ़्रेश टोकन के पुन: उपयोग से पूरा ऑथराइज़ेशन रिवोक हो जाता है। किसी क्लाइंट के भीतर रिफ़्रेश को सीरियलाइज़ करें; सफलतापूर्वक एक्सचेंज किए गए क्रेडेंशियल को फिर से चलाना सुरक्षित रीट्राई रणनीति नहीं है।

डिस्कनेक्ट करने के लिए POST /v1/oauth/revoke पर token और client_id भेजें। किसी भी टोकन को रिवोक करने से उसका ऑथराइज़ेशन रिवोक हो जाता है, जिसमें उससे जारी किए गए सभी टोकन शामिल हैं। अज्ञात टोकन, उसके मौजूद होने की जानकारी दिए बिना सफलता लौटाता है। डैशबोर्ड सेशन GET /v1/oauth/grants पर अपने ऑथराइज़ेशन सूचीबद्ध कर सकते हैं और X-ThunderPhone-Org द्वारा संगठन चुनते हुए DELETE /v1/oauth/grants/<id> पर किसी एक को रिवोक कर सकते हैं।

डिवाइस ऑथराइज़ेशन

डिवाइस ऑथराइज़ेशन केवल पहले से रजिस्टर्ड क्लाइंट्स तक सीमित है; डायनेमिक रूप से रजिस्टर्ड क्लाइंट्स को unauthorized_client प्राप्त होता है। पहले से रजिस्टर्ड सार्वजनिक क्लाइंट thunderphone-cli डिवाइस ऑथराइज़ेशन और रिफ़्रेश का समर्थन करता है। POST /v1/oauth/device/code पर client_id=thunderphone-cli और scope भेजें। यूज़र को 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 keys userinfo को कॉल नहीं कर सकते। कोई ID टोकन जारी नहीं किया जाता।

उपलब्ध अनुमतियां

परिवार	स्कोप
एजेंट और एजेंट इंपोर्ट	`agents:read`, `agents:write`
कॉल	`calls:read`, `calls:write`
फोन नंबर, ब्लॉक किए गए कॉलर और VoIP	`numbers:read`, `numbers:write`
नॉलेज	`knowledge:read`, `knowledge:write`
कैंपेन	`campaigns:read`, `campaigns:write`
इंटीग्रेशन, वेबहुक एंडपॉइंट और 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 key प्रबंधन और मानव अकाउंट सेटिंग्स सहित अन्य API फैमिली OAuth के माध्यम से उपलब्ध नहीं हैं। किसी REST ऑपरेशन पर अनुपस्थित अनुमति WWW-Authenticate: Bearer error="insufficient_scope", scope="..." के साथ 403 लौटाती है। अमान्य या समाप्त हो चुके एक्सेस टोकन 401 लौटाते हैं।

MCP टूल ऑथेंटिकेशन सिग्नल

tools/list के हर टूल में उस टूल के REST ऑपरेशन के स्कोप के साथ securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] शामिल होता है। पब्लिक डॉक्यूमेंटेशन टूल खाली स्कोप सूची का उपयोग करते हैं और फिर भी एक ऑथेंटिकेटेड कनेक्शन की आवश्यकता होती है।

किसी टूल का स्कोप न रखने वाला वैध टोकन HTTP 200 प्राप्त करता है, जिसमें JSON-RPC result में isError: true, content में व्याख्यात्मक टेक्स्ट, और _meta["mcp/www_authenticate"] होता है। बाद वाला एक ऐरे है जिसमें resource_metadata, error="insufficient_scope", error_description, और आवश्यक scope वाला Bearer चैलेंज शामिल होता है। टूल निष्पादित नहीं होता है। विस्तारित सहमति का अनुरोध करने के लिए इस चैलेंज का उपयोग करें। अनुपस्थित या अमान्य ऑथेंटिकेशन HTTP 401 के साथ WWW-Authenticate लौटाना जारी रखता है; REST स्कोप विफलताएं HTTP 403 लौटाना जारी रखती हैं।

क्रेडेंशियल रिटेंशन

API स्टेजिंग और प्रोडक्शन में हर घंटे python manage.py oauth_cleanup चलाता है। यह समाप्त हो चुके ऑथराइज़ेशन अनुरोध और डिवाइस कोड हटाता है। समाप्त हो चुके एक्सेस टोकन, ऑथराइज़ेशन कोड और रिफ्रेश-टोकन हैश केवल उनके ग्रांट के रिवोक होने या पूरी फैमिली के निष्क्रिय होने के बाद हटाए जाते हैं। उपयोग किए गए हैश तब तक रखे जाते हैं जब तक फैमिली के पास उपयोग योग्य रिफ्रेश टोकन, ऑथराइज़ेशन कोड, अनुमोदित डिवाइस कोड या एक्सेस टोकन होता है, इसलिए क्लीनअप रीप्ले डिटेक्शन को निष्क्रिय नहीं कर सकता।