Open in

OAuth सह कनेक्ट करा

API की शेअर न करता MCP क्लायंट्स आणि ThunderPhone CLI अधिकृत करा.

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) समर्थित नाहीत.

सार्वजनिक क्लायंट नोंदवा

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 तपासा. नकार आणि प्रोटोकॉल त्रुटींसह प्रत्येक ऑथरायझेशन प्रतिसाद 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 मंजूर करते, त्यामुळे क्लायंटने आवश्यक परवानग्यांची विनंती करावी.

कोडचा पुनर्वापर आणि रोटेट केलेल्या रिफ्रेश टोकनचा पुनर्वापर संपूर्ण ऑथरायझेशन रद्द करतात. क्लायंटमध्ये रिफ्रेशेस अनुक्रमित करा; यशस्वीपणे एक्सचेंज केलेले क्रेडेन्शियल पुन्हा पाठवणे ही सुरक्षित पुन्हा-प्रयत्न धोरण नाही.

डिस्कनेक्ट करण्यासाठी, 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 की 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-की व्यवस्थापन आणि मानवी खाते सेटिंग्जसह इतर API फॅमिलीज OAuth द्वारे उपलब्ध नाहीत. REST ऑपरेशनसाठी परवानगी नसल्यास 403 सह WWW-Authenticate: Bearer error="insufficient_scope", scope="..." परत मिळते. अवैध किंवा कालबाह्य ॲक्सेस टोकन्स 401 परत करतात.

MCP टूल प्रमाणीकरण संकेत

tools/list मधील प्रत्येक टूलमध्ये त्या टूलच्या REST ऑपरेशनच्या स्कोपसह securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] समाविष्ट असते. सार्वजनिक दस्तऐवज टूल्स रिकामी स्कोप सूची वापरतात आणि तरीही प्रमाणीकृत कनेक्शन आवश्यक असते.

टूलचा स्कोप नसलेल्या वैध टोकनला HTTP 200 मिळते, ज्यामध्ये isError: true असलेला JSON-RPC result, 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 चालवते. ते कालबाह्य अधिकृतता विनंत्या आणि डिव्हाइस कोड्स काढून टाकते. कालबाह्य ॲक्सेस टोकन्स, अधिकृतता कोड्स आणि रिफ्रेश-टोकन हॅशेस त्यांचे ग्रँट रद्द झाल्यावर किंवा संपूर्ण फॅमिली निष्क्रिय झाल्यावरच काढले जातात. फॅमिलीकडे वापरण्यायोग्य रिफ्रेश टोकन, अधिकृतता कोड, मंजूर डिव्हाइस कोड किंवा ॲक्सेस टोकन असेपर्यंत वापरलेले हॅशेस जतन केले जातात, त्यामुळे क्लीनअप रिप्ले शोध अक्षम करू शकत नाही.