ابنِ تكاملًا متعدد المستأجرين مع OAuth 2.1
دع مستخدميك يربطون نشاطهم التجاري على Crisphive بمنتجك — OAuth 2.1 مع شاشة موافقة، دون نسخ أي مفتاح API أبدًا.
مفاتيح API تصادق نشاطك التجاري أنت. عندما تبني منتجًا تتصل به أنشطة Crisphive تجارية أخرى — مزامنة CRM، أو ودجة حجز، أو موصل وكيل ذكاء اصطناعي — استخدم بدلًا من ذلك خادم تخويل OAuth 2.1 المدمج: يوافق كل مالك نشاط على تطبيقك عبر شاشة موافقة، ويتلقى تطبيقك رموزًا مرتبطة بمستأجر ذلك المالك.
/v1 ونقطة النهاية /mcp. أرسل Authorization: Bearer <access_token> تمامًا كما ترسل مفتاح API.التدفق
ينفّذ الخادم المسودة الحالية من OAuth 2.1: يتطلب PKCE (S256)، والعملاء عامّون (بدون سر)، والتسجيل ديناميكي — دون خطوة مراجعة يدوية للتطبيق:
| الخطوة | الطلب |
|---|---|
| 1. اكتشاف خادم التخويل | GET /.well-known/oauth-authorization-server (RFC 8414) → عناوين نقاط النهاية وأنواع المنح المدعومة |
| 2. التسجيل | POST /oauth/register (تسجيل العملاء الديناميكي RFC 7591) → client_id |
| 3. التخويل | GET /oauth/authorize?… — يسجّل مالك النشاط دخوله إلى Crisphive ويمنح موافقته |
| 4. الاستبدال | POST /oauth/token (grant_type=authorization_code، code، code_verifier) → { access_token, refresh_token, expires_in } |
| 5. التجديد | POST /oauth/token (grant_type=refresh_token) → زوج رموز مُدوّر (رمز التجديد القديم يُستخدم مرة واحدة) |
الرموز
الرمز مرتبط بنشاط المالك الموافِق ومنطقته وبيئته — فلا يمكنه أبدًا الوصول إلى مستأجر آخر أو التبديل بين live↔sandbox. اطلب scope أضيق (رموز أذونات مفصولة بمسافات، مثل customers_view job_requests_view) لتقييد الوصول؛ واحذفه للوصول الكامل إلى النشاط التجاري. تعيش رموز الوصول نحو ساعة واحدة؛ جدّد برمز التجديد أحادي الاستخدام لتبقى متصلًا.
عمر الاتصال
يخضع الاتصال لساعتين مستقلتين. التكامل المستخدم يوميًا لا يُفصل أبدًا وفق جدول؛ أمّا المنسي فتنتهي صلاحيته من تلقاء نفسه.
- نافذة الخمول — 30 يومًا. يُصدر كل تجديد للرمز رمز تجديد جديدًا صالحًا لمدة 30 يومًا أخرى. واصل استخدام الاتصال فيتمدّد إلى ما لا نهاية؛ وتوقّف 30 يومًا فينقضي.
- الحد الأقصى المطلق — 90 يومًا. بصرف النظر عن النشاط، ينتهي الاتصال بعد 90 يومًا من موافقة مالك النشاط التجاري عليه. يمكن للنشاط ضبط هذه المدة على أي قيمة من 1 إلى 365 يومًا لكل اتصال ضمن Developers → MCP connections؛ ويُحسب العدّ التنازلي من الموافقة الأصلية، لا من التغيير.
عند نفاد أيٍّ من الساعتين يفشل التجديد (OAUTH_GRANT_EXPIRED) ويجب أن يوافق المالك على التطبيق مجددًا من شاشة الموافقة. تعامل مع أي فشل في التجديد على أنه «أعد بدء تدفق التخويل»، لا كخطأ قابل لإعادة المحاولة أبدًا. يُرسَل بريد إلكتروني إلى مالكي النشاط التجاري ومسؤوليه قبل 14 يومًا من انتهاء صلاحية الاتصال — فإعادة الموافقة تتطلب حضور المالك في متصفح، لذا يأتي التحذير أبكر مما هو للمفاتيح.
استدعاء الواجهة
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer <access_token>"
تبني موصل وكيل ذكاء اصطناعي بدلًا من ذلك؟ يستخدم خادم MCP هذا التدفق نفسه — تنفّذه عملاء MCP المتوافقة تلقائيًا، فلا تكتب عادةً أي كود OAuth على الإطلاق.