---
title: "OAuth सह कनेक्ट करा"
description: "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` मिळते, ज्यामध्ये:

```http
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 पाठवा:

```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 देखील स्वीकारले जाते):

```text
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`) ला कॉल करा. यशस्वी प्रतिसादामध्ये हे असते:

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