إنتقل إلى المحتوى الرئيسي

OAuth لتطبيقات الشركاء

يمكن لتطبيق شريك أو أداة أتمتة أو تطبيق مخصص يعمل لصالح مستخدم MonoChat أن يستدعي واجهة الدوال المخصصة (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) باستخدام رمز وصول OAuth بدلًا من رمز API. يوافق المستخدم على التطبيق في صفحة من MonoChat، ويختار المؤسسات التي يمكنه الوصول إليها، ويمكنه إلغاؤه في أي وقت من التطبيقات المتصلة في إعدادات الملف الشخصي.

تظل رموز API تعمل على نقطة النهاية نفسها. OAuth هو الخيار لتطبيق يعمل نيابةً عن أشخاص آخرين: لا يرى أبدًا كلمة مرور أو رمز API، ويستطيع كل مستخدم قطعه بنفسه.

يعمل التطبيق بصفة المستخدم

يُنفَّذ الاستدعاء الذي يتم برمز وصول بصفة المستخدم الذي وافق على التطبيق وبأدواره. ولا يشغّل إلا الدوال المخصصة للمؤسسة، وفي المؤسسات التي يكون فيها المستخدم موظفًا فقط.

الحصول على عميل​

اطلب من MonoChat عميلًا لتطبيقك. يسجّله MonoChat بما يلي:

  • اسم التطبيق، الذي تعرضه صفحة الموافقة والتطبيقات المتصلة؛
  • عناوين URI لإعادة التوجيه، بتطابق تام: عناوين https، أو http على localhost أو 127.0.0.1 أو [::1] (أي منفذ)؛
  • النطاقات التي يمكنه طلبها: custom-functions:run لهذه الواجهة.

تحصل على معرّف عميل (يبدأ بـ monochat_rc_) وسر عميل (يبدأ بـ monochat_cs_). يُعرض السر مرة واحدة فقط، ولا يحفظ MonoChat إلا قيمته المجزّأة. احفظه على خادمك، ولا تضعه أبدًا في متصفح أو تطبيق جوال.

يمكن للتطبيق الذي لا يستطيع حفظ سر، مثل تطبيق يعمل في المتصفح أو على حاسوب المستخدم، أن يستخدم بدلًا من ذلك عنوان URL لمستند بيانات تعريف العميل كمعرّف للعميل، كما تفعل عملاء MCP. وعندها لا يرسل أي سر.

نقاط النهاية​

تسرد بيانات تعريف خادم التفويض على https://app.monochat.ai/.well-known/oauth-authorization-server كل نقاط النهاية. في تثبيت بعلامة بيضاء أو مستضاف ذاتيًا، استخدم عنوان ذلك التثبيت.

الإعدادالقيمة
نقطة نهاية التفويضhttps://app.monochat.ai/oauth/authorize
نقطة نهاية الرمزhttps://app.monochat.ai/oauth/token
نقطة نهاية الإلغاء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.
  2. يسجّل المستخدم الدخول إلى MonoChat إذا لزم الأمر. تعرض صفحة الموافقة اسم تطبيقك وتشغيل الدوال المخصصة نيابةً عنك. يمكن للمستخدم اختيار المؤسسات التي يمكن للتطبيق الوصول إليها (كلها إن لم يختر شيئًا)، ثم يُدخل رمز التأكيد المكوّن من 6 أرقام وينقر على السماح.
  3. يعيد MonoChat المستخدم إلى redirect_uri الخاص بك مع code وstate وiss. إذا نقر المستخدم على الرفض، فإنه يرسل error=access_denied بدلًا من ذلك.
  4. استبدل الرمز عند نقطة نهاية الرمز خلال 5 دقائق:
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 الممنوح.

استدعاء الواجهة​

أرسل رمز الوصول كرمز 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 لكل إذن و1200 لكل عميل، إضافةً إلى حد المؤسسة الخاص بنقطة النهاية هذه.

التحديث والإلغاء​

  • التحديث: قبل انتهاء صلاحية رمز الوصول، استدعِ نقطة نهاية الرمز مع grant_type=refresh_token وrefresh_token. كل تحديث يعيد رمز تحديث جديدًا؛ استخدم الجديد. رمز التحديث الذي يُستخدم مرة أخرى بعد أكثر من دقيقة من استبداله ينهي الإذن.
  • انتهاء الصلاحية: ينتهي الإذن بعد 90 يومًا من آخر تحديث، أو عندما يلغيه المستخدم من التطبيقات المتصلة، أو عندما يغيّر المستخدم كلمة مروره أو يعيد تعيينها. وعندها يجب على المستخدم الموافقة على التطبيق من جديد.
  • الإلغاء: لفصل مستخدم، أرسل رمز الوصول أو رمز التحديث إلى نقطة نهاية الإلغاء مع مصادقة عميلك:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

ربط المستخدم نفسه بتطبيقك مرة أخرى يحل محل إذنه السابق.