المصادقة

تعتمد الواجهة العامة على مصادقة بمفتاح حامل (bearer) واحد — لا يوجد تدفق OAuth، ولا زوج معرّف/سر للعميل، ولا ملفات تعريف ارتباط للجلسات.

إنشاء مفتاح

تُنشأ مفاتيح API وتُدار من صفحة مفاتيح API داخل تطبيق Logistall على الويب (قسم الإدارة في الشريط الجانبي). انظر في دليل المستخدم الأسئلة الشائعة للاطلاع على الخطوات، بما فيها متطلبات الصلاحيات ووحدة الميزات اللازمة لرؤية تلك الصفحة أصلًا.

عند إنشاء مفتاح، تُعرض لك قيمة السر الكاملة — التي تبدأ بـ lk_ — مرة واحدة، في حقل قابل للنسخ. بعد إغلاق ذلك المربع، لا يعرض Logistall القيمة الكاملة مجددًا أبدًا؛ ويعرض جدول مفاتيح API بعدها بادئة قصيرة فقط (أول 10 أحرف) لتميّز كل مفتاح عن غيره. إذا فقدت السر فلا سبيل لاسترداده — ألغِ المفتاح وأنشئ مفتاحًا جديدًا.

خلف الكواليس، لا يُخزَّن سوى تجزئة SHA-256 للمفتاح (api_key.key_hash)؛ فالسر الخام لا يُحفظ في أي مكان في قاعدة البيانات.

تقديم المفتاح

أرسل المفتاح مع كل طلب باستخدام أي من هذين الترويستين:

# Option 1: Authorization: Bearer
curl -H "Authorization: Bearer lk_YOUR_KEY" \
  https://tenant.logistall.cloud/api/v1/shipments?limit=10

# Option 2: X-API-Key
curl -H "X-API-Key: lk_YOUR_KEY" \
  https://tenant.logistall.cloud/api/v1/shipments?limit=10

إذا وُجدت الترويستان معًا، فالأولوية لـ Authorization: Bearer. المفتاح الذي لا يبدأ بـ lk_ — أو غياب المفتاح كليًا — يُرفض فورًا مع:

{ "error": "Missing or invalid API key" }

برمز الحالة HTTP ‏401.

أما المفتاح غير المعروف أو الملغى (الذي لا تطابق تجزئتُه أي مفتاح نشط) فيعيد:

{ "error": "Invalid API key" }

برمز الحالة HTTP ‏401 أيضًا.

نطاق المستأجر

المفاتيح مقيّدة بالشركة المستأجرة التي أُنشئت تحتها. مصادقة الطلب تحلّ المستأجر الذي يعود إليه عبر مطابقة التجزئة مع المفاتيح النشطة، فلا يمكن لمفتاح شركة أن يقرأ أبدًا بيانات شركة أخرى — لا توجد طريقة لتمرير معرّف مستأجر بنفسك، ولا شيء يحتاج إلى إعداد.

إلغاء مفتاح

إلغاء مفتاح من صفحة مفاتيح API يجعله غير نشط فورًا؛ وهو إلغاء ناعم (يُحتفظ بالصف للسجل التاريخي)، ولا يمكن إعادة تفعيل المفاتيح الملغاة — أنشئ مفتاحًا جديدًا إن احتجت إلى استعادة الوصول.

تتبع آخر استخدام

كل مصادقة ناجحة تحدّث الطابع الزمني last_used_at لذلك المفتاح، وهو ظاهر في جدول مفاتيح API، لتتمكن من رصد المفاتيح الراكدة أو التي لم تعد مستخدمة.

النطاقات

يحوي نموذج إنشاء المفتاح حقل النطاقات الاختياري كنص حر (مثل read:shipments write:routes). في الوقت الحالي تُخزَّن هذه القيمة على المفتاح لكنها غير مفروضة في أي موضع من الواجهة — فكل مفتاح صالح يستطيع قراءة كل نقاط النهاية /v1/*. تعامل مع النطاقات اليوم كوسم لتنظيمك الخاص، لا كآلية تحكم في الوصول.