المصادقة
تُصادَق الطلبات بمفتاح API سرّي يُرسَل كرمز حامل (bearer token) مع كل استدعاء.
ترويسة Authorization
أرفق مفتاح API الخاص بك كرمز حامل. تستخدم مفاتيح بيئة الاختبار البادئة chsk_test_، ومفاتيح الإنتاج البادئة chsk_live_.
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer chsk_test_4eC8xQ9mZ2pL7Ka0rT"
إدارة المفاتيح
أنشئ المفاتيح ضمن الإعدادات → المطوّرون — سمِّ المفتاح، وانسخ قيمته مرة واحدة عند الإنشاء، وقيّده بنطاقات أذونات محددة إن شئت، ويمكنك إبطاله في أي وقت.
لا يمكن لمفتاح أن يحمل أكثر مما يحمله منشئه: تُحدّ نطاقات المفتاح الجديد بأذونات المستخدم الذي ينشئه، حتى لو تُركت قائمة النطاقات فارغة. إذا طلب الإنشاء أكثر من ذلك، يفشل مع 403 API_KEY_SCOPE_NOT_GRANTED — دَع مستخدمًا بصلاحية وصول كاملة (أو مالكًا) ينشئ المفتاح إن احتجت إلى كامل النطاق.
انتهاء الصلاحية
تنتهي صلاحية مفاتيح API. تختار مدة صلاحية المفتاح عند إنشائه — 30 يومًا افتراضيًا، ومن 1 حتى 365 — وهي ثابتة طوال عمر ذلك المفتاح. لا يمكن تمديد مدة الصلاحية لاحقًا (إعادة تسمية المفتاح لا تغيّرها أبدًا)، لذا فإن expires_at الخاص بالمفتاح لا يتغيّر أبدًا. تُعيده واجهة API الخاصة بالمفاتيح ويُعرض في لوحة التحكم؛ اقرأه وخطّط لعملية التبديل.
يرسل Crisphive أيضًا بريدًا إلكترونيًا إلى مالكي النشاط التجاري ومسؤوليه قبل 7 أيام من انتهاء صلاحية المفتاح، ومرة أخرى بعد انتهائها. لا تعتمد على البريد الإلكتروني وحده — فهو يذهب إلى النشاط التجاري، وليس بالضرورة إليك؛ واصل قراءة expires_at وخطّط لعملية التبديل بنفسك.
تجديد مفتاح
للتجديد، أنشئ مفتاحًا جديدًا — لا توجد نقطة نهاية للتدوير. يمكن للنشاط التجاري الاحتفاظ بما يصل إلى 50 مفتاحًا نشطًا لكل بيئة، لذا لا يحتاج التسليم إلى أي آلية خاصة ولا يسبّب أي توقف:
أنشئ المفتاح البديل في لوحة التحكم.
انشر المفتاح الجديد في تكاملك.
تأكّد من تدفّق الحركة على المفتاح الجديد (last_used_at، أو Developers → Logs).
أبطل المفتاح القديم من لوحة التحكم.
هذا هو إجراء المفتاحين نفسه الذي توثّقه AWS لمفاتيح الوصول. حمّل المفتاح من الإعدادات ولا تكتبه في الكود أبدًا، فتصبح الخطوة 2 تغييرًا في الإعدادات لا إصدارًا جديدًا. أمّا المفتاح المسرّب فنفّذ الإجراء بالترتيب المعاكس — أبطِله أولًا ثم أنشئ البديل؛ فبضع استدعاءات فاشلة أهون من إبقاء مفتاح مخترَق حيًّا. إدارة المفاتيح تتم من لوحة التحكم فقط — لا توجد واجهة API عامة لإنشاء المفاتيح أو إبطالها.
401 مع error_code: "API_KEY_EXPIRED" — مميّز عمدًا عن API_KEY_INVALID (مُبطَل أو محذوف أو خاطئ)، حتى تتمكّن تنبيهاتك من التفريق بين تجديدٍ فائت وإبطال.العمل نيابةً عن أنشطة تجارية أخرى
مفاتيح API تصادق نشاطك التجاري أنت. هل تبني منتجًا تتصل به أنشطة Crisphive تجارية أخرى؟ استخدم OAuth 2.1 بدلًا من ذلك — يُخوّل كل مالك نشاط تطبيقَك عبر شاشة موافقة، ولا يُشارك أي مفتاح أبدًا.