OAuth 2.1
دع التطبيقات الأخرى تسجّل دخول مستخدميها بحساب Bot-Hosting، مثل «تسجيل الدخول عبر Discord». مبني على OAuth 2.1 وPKCE، فيعمل معه أي عميل OAuth قياسي.
استخدم مفتاح API للتحكم بحسابك الخاص. استخدم OAuth عندما تبني تطبيقًا يعمل على حسابات أشخاص آخرين، فيسجلون الدخول ويوافقون بدل لصق مفتاح. مساعدو الذكاء الاصطناعي مثل ChatGPT يتصلون عبر هذا المسار نفسه.
المسار
- 01 أنشئ تطبيقًا سجّل اسمًا وURI لإعادة التوجيه في إعدادات المطور. تحصل على client_id عام، دون سر.
- 02 وجّه المستخدمين للتفويض أعد التوجيه إلى /oauth/authorize مع PKCE. يسجّل المستخدم الدخول ويوافق على الصلاحيات.
- 03 استبدل الرمز يعود برمز. أرسله بـ POST إلى نقطة نهاية الرمز للحصول على رمز وصول.
- 04 استدعِ API نيابةً عنه أرسل الرمز كـ Bearer إلى /api/v1، وجدّده في الخلفية.
نقاط النهاية
| نقاط النهاية | الغرض |
|---|---|
| GET /oauth/authorize | شاشة موافقة المستخدم، تُفتح في المتصفح. |
| POST /api/oauth/token | استبدال رمز التفويض برمز وصول، أو تجديد رمز. |
| POST /api/oauth/register | تسجيل العميل الديناميكي (RFC 7591)، اختياري. |
| GET /.well-known/oauth-authorization-server | بيانات الاكتشاف الوصفية. |
| GET /.well-known/oauth-protected-resource | بيانات المورد الوصفية، تستخدمها عملاء MCP. |
مدد صلاحية الرموز
رمز التفويض 10 دقيقة للاستخدام مرة واحدة، مرتبط بـ PKCE.
رمز الوصول 7 أيام Bearer لاستدعاءات /api/v1.
رمز التجديد 30 أيام يُستبدل عند كل استخدام.
التجديد
كل تجديد يُرجع رمز تجديد جديدًا ويلغي القديم: استبدل المخزَّن دائمًا. إذا أرجع التجديد invalid_grant، أعد المستخدم إلى الخطوة 1.
الأمان
- خزّن الرموز على جهة الخادم، مرتبطة بمستخدمك. لا ترسلها أبدًا إلى المتصفح أو إلى مستودع عام.
- تُلغى الرموز لحظة فصل المستخدم تطبيقك.
- استخدم عناوين إعادة توجيه https في بيئة الإنتاج. يُقبل http للاختبار المحلي.
- رموز OAuth لا تمنح صلاحيات المشرف أبدًا، مهما كانت الصلاحيات الموافَق عليها.