OAuth کے ساتھ کنیکٹ کریں

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 موصول ہوتا ہے، جس کے ساتھ:

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 بھیجیں:

{
  "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 ہیڈر کے ذریعے بھیجیں۔ ٹوکنز کو کبھی 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 ہیڈر میں رسائی ٹوکن کے ساتھ کال کریں۔ کامیاب جواب میں شامل ہوتا ہے:

{
  "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 ٹوکن جاری نہیں کیا جاتا۔

دستیاب اجازتیں#

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 منسوخ ہو جائے یا پوری فیملی غیر فعال ہو جائے۔ استعمال شدہ ہیشز اس وقت تک برقرار رکھی جاتی ہیں جب فیملی کے پاس قابل استعمال ریفریش ٹوکن، اجازت کوڈ، منظور شدہ ڈیوائس کوڈ یا ایکسیس ٹوکن موجود ہو، تاکہ صفائی ری پلے کی شناخت کو غیر فعال نہ کر سکے۔