تخطي إلى المحتوى الرئيسي

مفاتيح 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)​

  1. سجّل الدخول إلى B1Admin بحساب يملك صلاحية تعديل الإعدادات.
  2. افتح الإعدادات ← المطوّر ← مفاتيح API.
  3. انقر على مفتاح API جديد، وأعطه اسمًا يسهل التعرف عليه (مثل "Zapier — مزامنة التبرعات")، واختر النطاقات التي يجب أن يملكها المفتاح، ثم انقر على حفظ.
  4. يُعرض المفتاح الكامل 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 والتطبيقات المتصلة بدلًا من ذلك.

مفتاح APIOAuth
من يثبّتهمسؤول كنيسة واحديوافق كل مسؤول كنيسة على التطبيق
ترويسة المصادقةAuthorization: Bearer cak_…Authorization: Bearer <jwt>
مدة صلاحية الرمزحتى الإلغاءالوصول ≈ 7 أيام، والتحديث ≈ 90 يومًا
الأنسب لـالنصوص البرمجية الداخلية، وموصلات Zapier/Make/Sheetsالتطبيقات الخارجية متعددة المستأجرين