مفاتيح API

يتضمن FORGE نظام إدارة مفاتيح API كامل لمنح التطبيقات والخدمات الخارجية وصولاً آمناً إلى واجهة API الخاصة بك. تدعم المفاتيح صلاحيات دقيقة وتحديد معدل الطلبات والانتهاء والإلغاء.

نظرة عامة

توفر مفاتيح API آلية مصادقة بديلة لجلسات المستخدم. صُممت للتكاملات بين الخوادم والتطبيقات المحمولة وأي نظام خارجي يحتاج لاستدعاء API برمجياً. كل مفتاح له مجموعة صلاحيات وحد معدل خاص به.

مخطط قاعدة البيانات

يخزن جدول api_keys جميع المفاتيح المُصدرة:

العمود	النوع	الوصف
id	UUID	المفتاح الأساسي
name	VARCHAR(255)	تسمية قابلة للقراءة (مثل "التطبيق المحمول")
key_hash	VARCHAR(64)	تجزئة SHA-256 للمفتاح الكامل
key_prefix	VARCHAR(8)	أول 8 أحرف للتعريف
permissions	JSONB	مصفوفة الإجراءات المسموحة
rate_limit	INTEGER	الحد الأقصى للطلبات في الدقيقة
last_used_at	TIMESTAMP	آخر وقت استُخدم فيه المفتاح
last_used_ip	VARCHAR(45)	عنوان IP لآخر طلب
request_count	BIGINT	إجمالي عدد الطلبات بهذا المفتاح
expires_at	TIMESTAMP	تاريخ انتهاء المفتاح (nullable لعدم الانتهاء)
revoked_at	TIMESTAMP	وقت إلغاء المفتاح (nullable)
revoked_by	UUID	المستخدم الذي ألغى المفتاح (nullable)
revoked_reason	TEXT	سبب الإلغاء (nullable)
created_by	UUID	المستخدم الذي أنشأ المفتاح
created_at	TIMESTAMP	طابع زمني لإنشاء السجل
updated_at	TIMESTAMP	طابع زمني لآخر تحديث

نموذج الأمان

تتبع مفاتيح API نموذج أمان للكتابة مرة واحدة:

مسار إنشاء المفتاح
─────────────────
1. المسؤول ينشئ مفتاح       → المفتاح الكامل يُرجع مرة واحدة
2. المفتاح يُجزّأ (SHA-256)  → فقط التجزئة تُخزّن
3. بادئة المفتاح تُحفظ       → أول 8 أحرف للعرض
4. المسؤول ينسخ المفتاح     → المفتاح لا يُعرض مجدداً

مسار التحقق من المفتاح
───────────────────
1. العميل يرسل رأس X-API-Key
2. الخادم يُجزّئ المفتاح المستلم
3. التجزئة تُقارن مع key_hash المُخزّن
4. الصلاحيات والانتهاء يُفحصان

تحذير

مفتاح API الكامل يُعرض مرة واحدة فقط عند الإنشاء. لا يمكن استرجاعه لاحقاً. إذا فُقد المفتاح، يجب إلغاؤه وإنشاء مفتاح جديد.

مصفوفة الصلاحيات

يخزن عمود permissions من نوع JSONB مصفوفة الإجراءات المسموحة:

["contents:read", "contents:write", "menus:read", "lookups:read"]

أنماط الصلاحيات الشائعة:

الصلاحية	الوصف
contents:read	قراءة صفحات المحتوى
contents:write	إنشاء وتحديث المحتوى
users:read	قراءة بيانات المستخدمين
users:write	إنشاء وتحديث المستخدمين
menus:read	قراءة بنية القوائم
lookups:read	قراءة قيم البحث
*	وصول كامل (كل الصلاحيات)

المصادقة

تُرسل مفاتيح API عبر رأس HTTP X-API-Key:

curl -X GET /api/contents \
  -H "X-API-Key: fk_a1b2c3d4e5f6g7h8i9j0..."

يتحقق الوسيط من المفتاح في كل طلب:

1. استخراج المفتاح من رأس X-API-Key
2. حساب تجزئة SHA-256
3. البحث عن التجزئة في جدول api_keys
4. التحقق من أن المفتاح غير منتهي (expires_at)
5. التحقق من أن المفتاح غير مُلغى (revoked_at)
6. التحقق من أن الإجراء المطلوب في مصفوفة permissions
7. تطبيق rate_limit
8. تحديث last_used_at و last_used_ip و request_count

نصيحة

مصادقة مفتاح API ومصادقة جلسة المستخدم متنافية حصرياً في طلب واحد. إذا قُدم كلاهما، يأخذ مفتاح API الأولوية.

تحديد المعدل

كل مفتاح API له rate_limit خاص (طلبات في الدقيقة). عند تجاوز الحد، يُرجع API:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

واجهة الإدارة

توفر لوحة الإدارة إدارة دورة حياة كاملة لمفاتيح API:

• إنشاء مفتاح -- تعيين الاسم والصلاحيات وحد المعدل والانتهاء الاختياري. المفتاح الكامل يُعرض مرة واحدة في مربع حوار سهل النسخ.
• عرض المفاتيح -- قائمة بكل المفاتيح تُظهر الاسم والبادئة والحالة وتاريخ آخر استخدام وعدد الطلبات.
• إلغاء مفتاح -- تعطيل مفتاح فوراً مع سبب اختياري. المفاتيح المُلغاة لا يمكن إعادة تفعيلها.

حالات المفتاح

الحالة	الشرط	قابل للاستخدام؟
نشط	غير منتهي، غير مُلغى	نعم
منتهي	expires_at في الماضي	لا
مُلغى	revoked_at مُعيّن	لا

تحذير

إلغاء المفتاح دائم ويسري فوراً. أي تكاملات تستخدم المفتاح المُلغى ستبدأ بتلقي استجابات 401 Unauthorized. نسّق مع المستهلكين الخارجيين قبل الإلغاء.

مسار التدقيق

جميع إجراءات مفاتيح API تُسجّل في سجل المراجعة. عند تقديم طلب بمفتاح API، يُملأ حقل api_key_id في سجل المراجعة، مما يوفر تتبعاً كاملاً لإجراءات الأطراف الثالثة.