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

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

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

```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 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` चलाता है। यह समाप्त हो चुके ऑथराइज़ेशन अनुरोध और डिवाइस कोड हटाता है। समाप्त हो चुके एक्सेस टोकन, ऑथराइज़ेशन कोड और रिफ्रेश-टोकन हैश केवल उनके ग्रांट के रिवोक होने या पूरी फैमिली के निष्क्रिय होने के बाद हटाए जाते हैं। उपयोग किए गए हैश तब तक रखे जाते हैं जब तक फैमिली के पास उपयोग योग्य रिफ्रेश टोकन, ऑथराइज़ेशन कोड, अनुमोदित डिवाइस कोड या एक्सेस टोकन होता है, इसलिए क्लीनअप रीप्ले डिटेक्शन को निष्क्रिय नहीं कर सकता।