---
title: "OAuth کے ساتھ کنیکٹ کریں"
description: "API کلید شیئر کیے بغیر MCP کلائنٹس اور ThunderPhone CLI کو مجاز بنائیں۔"
---

OAuth کسی ایپ کو آپ کی منظور کردہ اجازتوں کے ساتھ ایک ThunderPhone تنظیم سے منسلک ہونے دیتا ہے۔ ڈائریکٹری کلائنٹس کو بطور ڈیفالٹ OAuth استعمال کرنا چاہیے۔ ان کلائنٹس کے لیے تنظیم کی API keys دستیاب رہتی ہیں جنہیں دستی طور پر کنفیگر کردہ Bearer token درکار ہوتا ہے۔

## کنکشن منظور کریں

اپنے 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 ٹوکنز اور کلائنٹ ID میٹاڈیٹا دستاویزات (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` ہیڈر کے ذریعے بھیجیں۔ ٹوکنز کو کبھی URLs، لاگز، سورس کنٹرول، یا چیٹ میں نہ رکھیں۔

### ریفریش اور تنسیخ

ٹوکن اینڈ پوائنٹ پر `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` پر اپنی اجازتوں کی فہرست دیکھ سکتے ہیں اور `X-ThunderPhone-Org` کے ذریعے تنظیم منتخب کرتے ہوئے `DELETE /v1/oauth/grants/<id>` پر ایک اجازت منسوخ کر سکتے ہیں۔

### ڈیوائس اجازت

ڈیوائس اجازت صرف پہلے سے رجسٹر شدہ کلائنٹس تک محدود ہے؛ ڈائنامک طور پر رجسٹر شدہ کلائنٹس کو `unauthorized_client` موصول ہوتا ہے۔ پہلے سے رجسٹر شدہ عوامی کلائنٹ `thunderphone-cli` ڈیوائس اجازت اور ریفریش کو سپورٹ کرتا ہے۔ `client_id=thunderphone-cli` اور `scope` کو `POST /v1/oauth/device/code` پر بھیجیں۔ صارف کو `user_code` اور `verification_uri` دکھائیں، یا `verification_uri_complete` کھولیں۔

کم از کم واپس آنے والے `interval` (5 سیکنڈز) کا انتظار کرتے ہوئے، `grant_type=urn:ietf:params:oauth:grant-type:device_code`، `client_id`، اور `device_code` کے ساتھ ٹوکن اینڈ پوائنٹ کو پول کریں۔ `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`، دونوں طلب کریں۔ دریافت شدہ `userinfo_endpoint` (`GET /v1/oauth/userinfo`) کو Bearer ہیڈر میں رسائی ٹوکن کے ساتھ کال کریں۔ کامیاب جواب میں شامل ہوتا ہے:

```json
{
  "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` |
| فون نمبرز اور 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-key مینجمنٹ اور انسانی اکاؤنٹ سیٹنگز، OAuth کے ذریعے دستیاب نہیں ہیں۔ REST کارروائی پر اجازت موجود نہ ہونے کی صورت میں `403` کے ساتھ `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."` واپس آتا ہے۔ غلط یا میعاد ختم شدہ ایکسیس ٹوکنز `401` واپس کرتے ہیں۔


### MCP ٹول کی توثیق کے اشارے

`tools/list` میں ہر ٹول میں `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` شامل ہوتا ہے، جس میں اس ٹول کی REST کارروائی کا اسکوپ ہوتا ہے۔ عوامی دستاویزات کے ٹولز خالی اسکوپ فہرست استعمال کرتے ہیں اور پھر بھی توثیق شدہ کنکشن درکار ہوتا ہے۔

کسی ٹول کا اسکوپ نہ رکھنے والے درست ٹوکن کو 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، staging اور production میں ہر گھنٹے `python manage.py oauth_cleanup` چلاتی ہے۔ یہ میعاد ختم شدہ اجازت کی درخواستیں اور ڈیوائس کوڈز ہٹا دیتی ہے۔ میعاد ختم شدہ ایکسیس ٹوکنز، اجازت کوڈز اور ریفریش ٹوکن ہیشز صرف اس وقت حذف کیے جاتے ہیں جب ان کا grant منسوخ ہو جائے یا پوری فیملی غیر فعال ہو جائے۔ استعمال شدہ ہیشز اس وقت تک برقرار رکھی جاتی ہیں جب فیملی کے پاس قابل استعمال ریفریش ٹوکن، اجازت کوڈ، منظور شدہ ڈیوائس کوڈ یا ایکسیس ٹوکن موجود ہو، تاکہ صفائی ری پلے کی شناخت کو غیر فعال نہ کر سکے۔