مین مواد پر جائیں

پارٹنر ایپس کے لیے OAuth

کوئی پارٹنر ایپ، آٹومیشن ٹول یا کسٹم ایپ جو کسی MonoChat صارف کے لیے کام کرتی ہے، کسٹم فنکشن API (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) کو API ٹوکن کے بجائے OAuth رسائی ٹوکن سے کال کر سکتی ہے۔ صارف MonoChat کے ایک صفحے پر ایپ کو منظور کرتا ہے، وہ تنظیمیں چنتا ہے جن تک ایپ پہنچ سکتی ہے، اور پروفائل کی ترتیبات میں منسلک ایپس سے کسی بھی وقت اسے منسوخ کر سکتا ہے۔

API ٹوکنز اسی endpoint پر کام کرتے رہتے ہیں۔ OAuth اس ایپ کے لیے ہے جو دوسرے لوگوں کی جانب سے کام کرتی ہے: وہ کبھی پاس ورڈ یا API ٹوکن نہیں دیکھتی، اور ہر صارف خود اسے منقطع کر سکتا ہے۔

ایپ صارف کے طور پر کام کرتی ہے

رسائی ٹوکن سے کی گئی کال اس صارف کے طور پر، اس کے رولز کے ساتھ چلتی ہے جس نے ایپ منظور کی۔ یہ صرف تنظیم کے کسٹم میتھڈز چلاتی ہے، اور صرف ان تنظیموں میں جہاں صارف ایجنٹ ہے۔

کلائنٹ حاصل کریں​

اپنی ایپ کے لیے MonoChat سے کلائنٹ طلب کریں۔ MonoChat اسے ان کے ساتھ رجسٹر کرتا ہے:

  • ایپ کا نام، جو منظوری کا صفحہ اور منسلک ایپس دکھاتے ہیں؛
  • اس کے ری ڈائریکٹ URIs، بالکل مطابق: https پتے، یا localhost، 127.0.0.1 یا [::1] پر http (کوئی بھی پورٹ)؛
  • وہ اسکوپس جو وہ مانگ سکتی ہے: اس API کے لیے custom-functions:run۔

آپ کو ایک کلائنٹ ID (monochat_rc_ سے شروع) اور ایک کلائنٹ سیکرٹ (monochat_cs_ سے شروع) ملتا ہے۔ سیکرٹ صرف ایک بار دکھایا جاتا ہے؛ MonoChat صرف اس کا ہیش محفوظ کرتا ہے۔ اسے اپنے سرور پر رکھیں، کبھی براؤزر یا موبائل ایپ میں نہیں۔

جو ایپ سیکرٹ محفوظ نہیں رکھ سکتی، جیسے براؤزر میں یا صارف کے کمپیوٹر پر چلنے والی ایپ، وہ MCP کلائنٹس کی طرح کلائنٹ ID میٹا ڈیٹا دستاویز کا URL بطور کلائنٹ ID استعمال کر سکتی ہے۔ تب وہ کوئی سیکرٹ نہیں بھیجتی۔

Endpoints​

https://app.monochat.ai/.well-known/oauth-authorization-server پر موجود اتھارائزیشن سرور میٹا ڈیٹا تمام endpoints کی فہرست دیتا ہے۔ وائٹ لیبل یا خود ہوسٹ کی گئی انسٹالیشن پر اسی انسٹالیشن کا پتہ استعمال کریں۔

ترتیبقدر
اتھارائزیشن endpointhttps://app.monochat.ai/oauth/authorize
ٹوکن endpointhttps://app.monochat.ai/oauth/token
منسوخی endpointhttps://app.monochat.ai/oauth/revoke
ریسورسhttps://app.monochat.ai/api/custom-functions
اسکوپcustom-functions:run
کلائنٹ کی تصدیقHTTP Basic، یا درخواست کے باڈی میں client_id اور client_secret

ریسورس کا اپنا میٹا ڈیٹا https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions پر ہے۔

صارف کو جوڑیں​

MonoChat PKCE (S256) کے ساتھ اتھارائزیشن کوڈ فلو استعمال کرتا ہے۔ صارف کے پاس دو مرحلہ تصدیق (ای میل یا آتھنٹیکیٹر ایپ کے ذریعے) سیٹ ہونی چاہیے۔

  1. صارف کو اتھارائزیشن endpoint پر response_type=code، اپنی client_id، رجسٹرڈ redirect_uri، scope=custom-functions:run، resource=https://app.monochat.ai/api/custom-functions، ایک state اور code_challenge_method=S256 کے ساتھ ایک code_challenge کے ساتھ بھیجیں۔
  2. ضرورت ہو تو صارف MonoChat میں سائن ان کرتا ہے۔ منظوری کا صفحہ آپ کی ایپ کا نام اور آپ کی جانب سے کسٹم میتھڈز چلانا دکھاتا ہے۔ صارف وہ ادارے چن سکتا ہے جن تک ایپ پہنچ سکتی ہے (کوئی نہ چنے تو سب)، 6 ہندسوں کا تصدیقی کوڈ درج کرتا ہے اور اجازت دیں پر کلک کرتا ہے۔
  3. MonoChat صارف کو code، state اور iss کے ساتھ آپ کے redirect_uri پر واپس بھیجتا ہے۔ اگر صارف انکار کریں پر کلک کرے تو اس کے بجائے error=access_denied بھیجا جاتا ہے۔
  4. کوڈ کو 5 منٹ کے اندر ٹوکن endpoint پر بدلیں:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

جواب میں expires_in سیکنڈ (ایک گھنٹہ) کے لیے درست access_token (monochat_at_ سے شروع)، ایک refresh_token (monochat_rt_ سے شروع) اور دیا گیا scope ہوتا ہے۔

API کال کریں​

رسائی ٹوکن کو bearer ٹوکن کے طور پر بھیجیں:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
اسٹیٹسکب
401ٹوکن نامعلوم، میعاد ختم یا منسوخ ہے، یا کسی دوسرے ریسورس جیسے MCP سرور کے لیے جاری ہوا ہے۔ WWW-Authenticate ہیڈر ریسورس میٹا ڈیٹا کی طرف اشارہ کرتا ہے۔
403تنظیم ان میں سے نہیں جن کی صارف نے ایپ کو اجازت دی، صارف کو تنظیم تک رسائی نہیں، یا اجازت میں custom-functions:run شامل نہیں۔
429کوئی حد پوری ہو گئی؛ Retry-After میں دیے گئے سیکنڈز انتظار کریں۔ کالز فی منٹ گنی جاتی ہیں: فی اجازت 120 اور فی کلائنٹ 1,200، اس endpoint کے لیے تنظیم کی اپنی حد کے علاوہ۔

ریفریش اور منسوخی​

  • ریفریش: رسائی ٹوکن کی میعاد ختم ہونے سے پہلے grant_type=refresh_token اور refresh_token کے ساتھ ٹوکن endpoint کال کریں۔ ہر ریفریش نیا ریفریش ٹوکن واپس کرتا ہے؛ نیا استعمال کریں۔ بدلے جانے کے ایک منٹ سے زیادہ بعد دوبارہ استعمال ہونے والا ریفریش ٹوکن اجازت ختم کر دیتا ہے۔
  • میعاد: اجازت آخری ریفریش کے 90 دن بعد، جب صارف اسے منسلک ایپس سے منسوخ کرے، یا جب صارف اپنا پاس ورڈ بدلے یا ری سیٹ کرے، ختم ہو جاتی ہے۔ پھر صارف کو ایپ دوبارہ منظور کرنی ہوتی ہے۔
  • منسوخی: کسی صارف کو منقطع کرنے کے لیے رسائی یا ریفریش ٹوکن اپنی کلائنٹ تصدیق کے ساتھ منسوخی endpoint پر بھیجیں:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

اسی صارف کو آپ کی ایپ سے دوبارہ جوڑنا اس کی پچھلی اجازت کی جگہ لے لیتا ہے۔