پارٹنر ایپس کے لیے 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 کی فہرست دیتا ہے۔ وائٹ لیبل یا خود ہوسٹ کی گئی انسٹالیشن پر اسی انسٹالیشن کا پتہ استعمال کریں۔
| ترتیب | قدر |
|---|---|
| اتھارائزیشن endpoint | https://app.monochat.ai/oauth/authorize |
| ٹوکن endpoint | https://app.monochat.ai/oauth/token |
| منسوخی endpoint | https://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) کے ساتھ اتھارائزیشن کوڈ فلو استعمال کرتا ہے۔ صارف کے پاس دو مرحلہ تصدیق (ای میل یا آتھنٹیکیٹر ایپ کے ذریعے) سیٹ ہونی چاہیے۔
- صارف کو اتھارائزیشن 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کے ساتھ بھیجیں۔ - ضرورت ہو تو صارف MonoChat میں سائن ان کرتا ہے۔ منظوری کا صفحہ آپ کی ایپ کا نام اور آپ کی جانب سے کسٹم میتھڈز چلانا دکھاتا ہے۔ صارف وہ ادارے چن سکتا ہے جن تک ایپ پہنچ سکتی ہے (کوئی نہ چنے تو سب)، 6 ہندسوں کا تصدیقی کوڈ درج کرتا ہے اور اجازت دیں پر کلک کرتا ہے۔
- MonoChat صارف کو
code،stateاورissکے ساتھ آپ کےredirect_uriپر واپس بھیجتا ہے۔ اگر صارف انکار کریں پر کلک کرے تو اس کے بجائےerror=access_deniedبھیجا جاتا ہے۔ - کوڈ کو 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>
اسی صارف کو آپ کی ایپ سے دوبارہ جوڑنا اس کی پچھلی اجازت کی جگہ لے لیتا ہے۔