مفاتيح API
مفاتيح API (رموز الوصول الشخصية) هي أبسط طريقة للمصادقة مع واجهة B1 البرمجية من خلال نص برمجي على الخادم، أو موصل تابع لجهة خارجية (Zapier، وMake، وGoogle Sheets)، أو في أي حالة لا يكون فيها تدفق OAuth الكامل ضروريًا. يرتبط المفتاح بشخص محدد في كنيسة محددة، ويرث صلاحيات ذلك الشخص، مع تقييدها بمجموعة اختيارية من النطاقات.
قبل أن تبدأ
- يقوم مسؤول الكنيسة الذي يملك صلاحية تعديل الإعدادات بإنشاء المفاتيح وإدارتها
- يُعرض المفتاح الخام مرة واحدة فقط عند إنشائه، لذا احفظه في مكان آمن فورًا
- يجب أن تستخدم جميع طلبات API بروتوكول HTTPS
تنسيق المفتاح
يبدو مفتاح API في B1 كالتالي:
cak_<prefix>.<secret>
cak_— معرّف ثابت (بادئة مفتاح API التي تطابقها طبقة المصادقة)<prefix>— جزء بحث عام مكون من 8 أحرف<secret>— سر مكون من 48 حرفًا؛ لا يُخزَّن على الخادم إلا تجزئة SHA-256 الخاصة به
يُرسل المفتاح الكامل إلى الخادم في ترويسة Bearer القياسية:
Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7
تُوجِّه طبقة مصادقة API أي رمز يبدأ بـ cak_ إلى مسار مفاتيح API، فتُجزِّئ السر، وتبحث عنه بحسب البادئة، ثم تحدد الصلاحيات الحالية للشخص المرتبط بالمفتاح. لذلك يسري سحب صلاحية من B1Admin فور الطلب التالي، ولا يصبح المفتاح غير متزامن مع الدور أبدًا.
إنشاء مفتاح (B1Admin)
- سجّل الدخول إلى B1Admin بحساب يملك صلاحية تعديل الإعدادات.
- افتح الإعدادات ← المطوّر ← مفاتيح API.
- انقر على مفتاح API جديد، وأعطه اسمًا يسهل التعرف عليه (مثل "Zapier — مزامنة التبرعات")، واختر النطاقات التي يجب أن يملكها المفتاح، ثم انقر على حفظ.
- يُعرض المفتاح الكامل
cak_…مرة واحدة في نافذة حوار. انسخه إلى إعدادات تكاملك قبل إغلاق النافذة، إذ لا توجد طريقة لاسترجاعه لاحقًا. ويمكنك دائمًا إنشاء مفتاح جديد.
النطاقات
يُقيِّد النطاق ما يمكن للمفتاح فعله، ولا يمكنه أبدًا منح صلاحية لا يملكها الشخص الأساسي. وإذا لم تُحدَّد أي نطاقات، أو كانت الحقول فارغة، فإن المفتاح يحمل مجموعة الصلاحيات الكاملة للشخص.
| النطاق | يسمح بـ |
|---|---|
people:read / people:write | عرض الأشخاص والعائلات وأعضاء المجموعات / تعديلها |
groups:read / groups:write | عرض المجموعات وعضويتها / تعديلها |
donations:read / donations:write | عرض التبرعات / تسجيلها |
attendance:read / attendance:write | عرض الحضور والجلسات وتسجيلات الوصول / تسجيلها |
forms:write | إدارة النماذج (صلاحية القراءة متضمنة ضمنيًا في صلاحية الكتابة) |
content:read / content:write | عرض محتوى الموقع والتسجيلات والبث / تعديلها |
messaging:read / messaging:write | قراءة الرسائل؛ وتتيح صلاحية الكتابة أيضًا إرسال الرسائل النصية القصيرة |
roles:read / roles:write | عرض تعريفات الأدوار / تعديلها |
settings:read / settings:write | عرض إعدادات الكنيسة / تعديلها (مطلوب لتسجيل الخطافات الإلكترونية برمجيًا) |
workflows:read / workflows:write | عرض سير العمل والمهام / تشغيل سير العمل وتعديله. قد يؤدي تشغيل سير العمل إلى إرسال رسائل بريد إلكتروني ونصية، وتفعيل خطافات إلكترونية، وتغيير عضوية المجموعات |
offline_access | السماح برموز التحديث طويلة الأمد (لتدفقات OAuth فقط، ولا تأثير لها على مفاتيح API) |
تتضمن صلاحيات write ضمنيًا صلاحية read المقابلة لها. لم تُعرَّض صلاحيات المسؤول على مستوى الخادم أو النطاق كنطاقات عن قصد، لذلك لا يمكن لبيانات اعتماد مقيّدة النطاق أن ترفع صلاحياتها إلى إدارة الموقع.
إذا كنت ستستخدم المفتاح لتسجيل الخطافات الإلكترونية (مثلًا لتكامل Zapier أو Make)، فيجب أن يملك المفتاح صلاحية settings:write. أما المفتاح الذي يملك صلاحية people:read فقط، فسيُرفض بصمت برمز 403 عند استدعاء POST /membership/webhooks.
استخدام المفتاح
يعمل المفتاح كأي رمز Bearer آخر، إذ تقبل كل نقطة نهاية موثّقة مفاتيح API تمامًا كما تقبل رموز JWT:
curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"
إذا كانت نطاقات المفتاح غير كافية للطلب، فسيُرجع الخادم استجابة 403 Forbidden بالبنية نفسها التي يستخدمها أي خطأ رفض صلاحيات.
إدارة المفاتيح عبر API
تقع جميع نقاط النهاية ضمن المسار /membership/apiKeys في وحدة العضوية، وتتطلب رمز JWT (وليس مفتاح API) من مسؤول كنيسة يملك صلاحية تعديل الإعدادات.
| الطريقة والمسار | الغرض |
|---|---|
GET /membership/apiKeys | عرض مفاتيح الكنيسة (بدون السر، وتتضمن فقط id وname وprefix وscopes وlastUsedAt وexpiresAt وcreatedAt) |
GET /membership/apiKeys/scopes | قائمة بجميع أسماء النطاقات المتاحة، لاستخدامها في واجهة إنشاء المفاتيح |
POST /membership/apiKeys | إنشاء مفتاح جديد. نص الطلب: { "name": "...", "scopes": ["people:read"] }. تتضمن الاستجابة المفتاح الخام cak_… مرة واحدة فقط. |
DELETE /membership/apiKeys/:id | إلغاء مفتاح، ويسري الإلغاء عند الطلب التالي |
يُلغى المفتاح المسحوب فورًا، ولا توجد فترة سماح.
أفضل الممارسات
- مفتاح واحد لكل تكامل. إذا تعرّض أحد المفاتيح للاختراق، فيمكنك إلغاؤه وحده دون تعطيل التكاملات الأخرى.
- أنشئ أضيق النطاقات التي تؤدي المطلوب. يحتاج تصدير Google Sheets إلى
people:readفقط، وليسsettings:write. - اربط المفتاح بحساب خدمة، وليس بموظف حقيقي. إذا غادر أحد الموظفين، ينتهي وصوله إلى B1، وتنتهي معه أيضًا أي مفاتيح أُنشئت باسمه.
- خزّن المفاتيح في مدير أسرار (مثل متغيرات البيئة لدى مزود الاستضافة، أو AWS Secrets Manager، وغيرها)، ولا تحفظها أبدًا في نظام التحكم بالإصدارات.
- دوّر المفاتيح إذا اشتبهت في تعرضها للكشف: أنشئ مفتاحًا جديدًا، وحدّث التكامل، ثم احذف المفتاح القديم.
الفرق بينها وبين OAuth
تناسب مفاتيح API الحالات التي تكون فيها كنيستك هي الوحيدة التي تستخدم التكامل. أما الموصل الذي يحتاج إلى الوصول إلى كنائس كثيرة، مع موافقة صريحة من كل كنيسة، مثل تطبيق SaaS يُشارَك داخل مجتمع B1، فاستخدم OAuth والتطبيقات المتصلة بدلًا من ذلك.
| مفتاح API | OAuth | |
|---|---|---|
| من يثبّته | مسؤول كنيسة واحد | يوافق كل مسؤول كنيسة على التطبيق |
| ترويسة المصادقة | Authorization: Bearer cak_… | Authorization: Bearer <jwt> |
| مدة صلاحية الرمز | حتى الإلغاء | الوصول ≈ 7 أيام، والتحديث ≈ 90 يومًا |
| الأنسب لـ | النصوص البرمجية الداخلية، وموصلات Zapier/Make/Sheets | التطبيقات الخارجية متعددة المستأجرين |