پرش به مطلب اصلی

OAuth برای برنامه‌های شریک

یک برنامه شریک، ابزار خودکارسازی یا برنامه سفارشی که برای یک کاربر MonoChat کار می‌کند، می‌تواند API تابع‌های سفارشی (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) را با توکن دسترسی OAuth به‌جای توکن API فراخوانی کند. کاربر برنامه را در یک صفحه MonoChat تأیید می‌کند، سازمان‌هایی را که برنامه به آن‌ها دسترسی دارد انتخاب می‌کند و هر زمان بخواهد می‌تواند آن را از برنامه‌های متصل در تنظیمات پروفایل لغو کند.

توکن‌های API روی همان endpoint همچنان کار می‌کنند. OAuth گزینه‌ای برای برنامه‌ای است که از طرف دیگران عمل می‌کند: هرگز رمز عبور یا توکن API را نمی‌بیند و هر کاربر می‌تواند خودش آن را قطع کند.

برنامه به‌عنوان کاربر عمل می‌کند

فراخوانی با توکن دسترسی به‌عنوان کاربری که برنامه را تأیید کرده و با نقش‌های او اجرا می‌شود. فقط متدهای سفارشی سازمان را اجرا می‌کند و فقط در سازمان‌هایی که کاربر در آن‌ها کارشناس است.

دریافت کلاینت​

برای برنامه خود از MonoChat یک کلاینت بخواهید. MonoChat آن را با این موارد ثبت می‌کند:

  • نام برنامه که صفحه تأیید و برنامه‌های متصل نشان می‌دهند؛
  • URIهای بازگشت با تطابق دقیق: نشانی‌های https، یا http روی localhost، 127.0.0.1 یا [::1] (هر پورت)؛
  • دامنه‌هایی که می‌تواند درخواست کند: برای این API، custom-functions:run.

یک شناسه کلاینت (با monochat_rc_ شروع می‌شود) و یک رمز کلاینت (با monochat_cs_ شروع می‌شود) دریافت می‌کنید. رمز فقط یک بار نشان داده می‌شود و MonoChat فقط هش آن را نگه می‌دارد. آن را روی سرور خود نگه دارید، هرگز در مرورگر یا برنامه موبایل.

برنامه‌ای که نمی‌تواند رمز را محرمانه نگه دارد، مثل برنامه‌ای که در مرورگر یا روی رایانه کاربر اجرا می‌شود، می‌تواند مانند کلاینت‌های MCP، نشانی URL یک سند فراداده کلاینت را به‌عنوان شناسه کلاینت به کار ببرد. در این حالت رمزی نمی‌فرستد.

Endpointها​

فراداده سرور مجوزدهی در https://app.monochat.ai/.well-known/oauth-authorization-server همه endpointها را فهرست می‌کند. در نصب برچسب سفید یا میزبانی‌شده توسط خودتان، از نشانی همان نصب استفاده کنید.

تنظیممقدار
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) استفاده می‌کند. کاربر باید تأیید دومرحله‌ای (با ایمیل یا برنامه احراز هویت) را تنظیم کرده باشد.

  1. کاربر را با response_type=code، client_id خود، یک redirect_uri ثبت‌شده، scope=custom-functions:run، resource=https://app.monochat.ai/api/custom-functions، یک state و یک code_challenge همراه با code_challenge_method=S256 به endpoint مجوزدهی بفرستید.
  2. کاربر در صورت نیاز وارد MonoChat می‌شود. صفحه تأیید نام برنامه شما و اجرای متدهای سفارشی از طرف شما را نشان می‌دهد. کاربر می‌تواند سازمان‌ها قابل دسترس برای برنامه را انتخاب کند (اگر هیچ‌کدام را انتخاب نکند، همه)، کد تأیید ۶ رقمی را وارد می‌کند و روی اجازه کلیک می‌کند.
  3. MonoChat کاربر را با code، state و iss به redirect_uri شما برمی‌گرداند. اگر کاربر روی رد کلیک کند، به‌جای آن error=access_denied فرستاده می‌شود.
  4. کد را ظرف ۵ دقیقه در 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>

پاسخ شامل یک access_token (با monochat_at_ شروع می‌شود) با اعتبار expires_in ثانیه (یک ساعت)، یک 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 صبر کنید. فراخوانی‌ها در دقیقه شمرده می‌شوند: ۱۲۰ برای هر مجوز و ۱۲۰۰ برای هر کلاینت، به‌علاوه محدودیت خود سازمان برای این endpoint.

تازه‌سازی و لغو​

  • تازه‌سازی: پیش از انقضای توکن دسترسی، endpoint توکن را با grant_type=refresh_token و refresh_token فراخوانی کنید. هر تازه‌سازی یک توکن تازه‌سازی جدید برمی‌گرداند؛ از توکن جدید استفاده کنید. توکن تازه‌سازی‌ای که بیش از یک دقیقه پس از جایگزینی دوباره به کار رود، مجوز را پایان می‌دهد.
  • انقضا: مجوز ۹۰ روز پس از آخرین تازه‌سازی، وقتی کاربر آن را از برنامه‌های متصل لغو کند، یا وقتی کاربر رمز عبورش را تغییر دهد یا بازنشانی کند، پایان می‌یابد. پس از آن کاربر باید برنامه را دوباره تأیید کند.
  • لغو: برای قطع اتصال یک کاربر، توکن دسترسی یا تازه‌سازی را همراه با احراز هویت کلاینت خود به endpoint لغو بفرستید:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

اتصال دوباره همان کاربر به برنامه شما، مجوز قبلی او را جایگزین می‌کند.