الأمان

التفويض بالمفتاح وحده

يعرّف العقد مخططي أمان فقط، وكلاهما يحمل السر نفسه:

المخطط	الترويسة	ملاحظات
ApiKeyHeader	X-API-Key	موصى به.
BearerAuth	Authorization: Bearer	مكافئ. استخدمه عندما تُصرّ مكتبة عميل على رمز Bearer.

كلا الشكلين يُحلّ إلى بيانات الاعتماد نفسها. وGET /v1/products هي نقطة النهاية الوحيدة التي تقبل نداءً غير موثّق.

لا توجد قائمة سماح لعناوين IP. فحد المعدل لكل IP سقف يتقاسمه كل ما يقف خلف عنوان واحد — إنه يحدّ من إساءة الاستخدام، ولا يمنح وصولًا ولا يمنعه. تعامل مع المفتاح كحد السلطة الكامل لحسابك.

المفتاح

مفتاح Zelnum API هو ck_ متبوعة بـ 48 حرفًا: 51 إجمالًا. وأي شيء أقصر ليس مفتاحًا، وهو فحص مفيد عندما يُفسد مدير أسرار قيمةً.

افعل	لا تفعل
احفظه في مدير أسرار أو متغير بيئة	ضعه في مستودع، أو ملف إعداد يمكن للمستخدمين قراءته، أو سجل CI
أرسله من خادمك	ضعه في JavaScript المتصفح، أو حزمة تطبيق جوال، أو أي عميل عام
اقرأ api_key_id عندما تحتاج إلى تحديد المفتاح	الصق المفتاح نفسه في طلب دعم
احجبه في السجلات	سجّل ترويسات الطلب كاملة

المفتاح داخل حزمة واجهة أمامية ليس سرًا. وإذا احتاج تكامل إلى نداء الـ API من متصفح، فليستدعِ المتصفح خادمك أنت وليحتفظ خادمك بالمفتاح — فسقف الـ IP على الحركة التي تبدو غير موثّقة لن ينقذك.

تخزّن قاعدة البيانات تجزئة SHA-256 وبادئة عرض من 9 أحرف، لا القيمة نفسها أبدًا، فحتى لو تسرّبت نسخة كاملة لا يحصل أحد على رمز صالح للاستخدام. والوجه الآخر أن لا نقطة نهاية تستطيع إعادة مفتاحك: إن فقدته، فدوّره.

تأكيد أي مفتاح حيّ

curl -X GET "https://api.zelnum.com/api/v1/api-key" \
  -H "X-API-Key: YOUR_KEY_HERE"

تحمل الاستجابة api_key_id وmasked_key وlast_used وcreated_at — لأحدث مفتاح نشط صادر على الحساب. وتُبلّغ نقطة النهاية عن مفتاح واحد، فاقرأها على أنها “المفتاح الذي كنت سأستخدمه الآن”، لا كجرد. ولرؤية كل المفاتيح، استخدم لوحة التحكم.

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

تدوير مفتاح

يمكن للحساب أن يحمل عدة مفاتيح نشطة في آن واحد، وتديرها لوحة التحكم فرادى:

إجراء لوحة التحكم	الأثر
إنشاء	يضيف مفتاحًا. وكل مفتاح قائم يظل يعمل.
إعادة توليد	يعطّل ذلك المفتاح ويصدر بديلًا بالاسم نفسه. فيتوقف الأصلي عن العمل فورًا.
حذف	يزيل المفتاح نهائيًا.

وهذا يمنحك شكلين للتدوير، والخيار هو ما إذا كنت تستطيع تحمّل نافذة تداخل.

أنشئ مفتاحًا ثانيًا — التدوير التدريجي، وهو المفضَّل:

1. أنشئ المفتاح الجديد في لوحة التحكم. لا يتغيّر شيء آخر؛ والمفتاح القديم ما زال يوّثق الطلبات.
2. انشر القيمة الجديدة في كل مكان تحتاجها فيه — خوادم التطبيقات، والعمال، ومهام cron، والسكربتات المجدولة — من دون تفعيلها بعد.
3. حوّل عمليات النشر. وتحقق عبر GET /v1/api-key حتى تُبلّغ عن api_key_id الجديد، مع مراعاة دقة الخمس دقائق لـ last_used.
4. احذف المفتاح القديم متى لم يعد شيء ينادي به. فهذه هي الخطوة التي تزيل بيانات الاعتماد فعلًا — ولا يكتمل التدوير قبل إتمامها.

أعد التوليد في المكان — عندما يجب أن تموت القيمة القديمة الآن:

استخدم هذا عندما يُكشف مفتاح ويصبح أي استمرار لصلاحيته عبئًا.

1. اقبل الفجوة. يتوقف المفتاح القديم عن العمل لحظة إعادة التوليد، فيعيد كل مكوّن ما زال يحمله 401 unauthorized حتى يُعاد نشره. لا يوجد تداخل، بحكم التصميم.
2. أعد التوليد في لوحة التحكم وانسخ القيمة النصية الصريحة من الشريط فورًا — فهي تُعرض هناك ولا في مكان آخر، أبدًا بعد ذلك.
3. انشر القيمة الجديدة، ثم تأكد من أن شيئًا لم يعد يسجّل 401.

القيمة النصية الصريحة تُعرض مرة واحدة

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

النقل

كل نقطة نهاية عبر HTTPS. لا يوجد مستمع غير مشفّر، ولا تقبل أي نقطة نهاية تخفيضًا، فلا يوجد إعداد ينتقل فيه مفتاح دون تشفير.

إذا بنيت وكيلًا أو بوابة أمام الـ API، فأنهِ TLS عند الطرف ومرّر ترويسة X-API-Key — لا تعد كتابتها، ولا تضفها إلى سجلات الطلبات الواردة.

ما ترسله، ومدة الاحتفاظ به

مدخلات الـ API أرقام هواتف وعناوين بريد إلكتروني — أي بيانات شخصية في معظم النظم القانونية. ونتيجتان:

• أرسل ما تحتاجه فقط. لا يحتاج الفحص إلا إلى المعرّف ولا شيء غيره. لا تضف معرّف مستخدم أو مرجعًا داخليًا أو بيانات وصفية نصية حرة إلى جسم الطلب: فهي لا تُخزَّن كحقل، وإنما توسّع تعرّض سجلاتك أنت فقط.
• اعرف نوافذ الاحتفاظ. تُحتفظ بسجلات الوقت الفعلي ونتائج الإعادة لمدة 30 يومًا افتراضيًا، وبملفات النتائج الجماعية لمدة 7 أيام (result_retention_days). وبعد هذه النوافذ تزول السجلات، فصدّر كل ما يلزمك الاحتفاظ به.

تعامل مع الرقم كبيانات حساسة في أنظمتك أنت أيضًا. فنتيجة الفحص تخبر المراقب ما إذا كان شخص بعينه مسجّلًا على منصة بعينها، وقرين المعرّف والحكم أكثر كشفًا من أي من نصفيه.

حماية نفسك من الاحتساب المزدوج

هذه خاصية أمان بقدر ما هي خاصية فوترة: فـ Idempotency-Key يجعل إعادة المحاولة آمنة، فلا يمكن لعطل شبكة أو مشغّل غير صبور أن يحوّل احتسابًا واحدًا إلى اثنين. لا تولّد مفتاحًا جديدًا أبدًا لإعادة محاولة طلب لم ترصد نتيجته — راجع عدم التكرار وإعادة المحاولة.

التالي

• الحالة والدعم — ما يجب تضمينه عند التصعيد، دون تسريب المفتاح
• رموز الأخطاء — unauthorized وaccount_banned في سياقهما