واجهة API للشركاء (B2B)
المصادقة
Authenticate with an API key from the partner portal, and rotate, restrict or revoke keys.
On this page
صيغة المفتاح#
esk_live_<prefix:10>_<secret:40>المفتاح سلسلة أبجدية رقمية تتكون من بادئة من 10 أحرف (معرّف عام يظهر في البوابة) وسرّ من 40 حرفًا. لا تخزّن esimoa سوى تجزئة SHA-256، لذا يُعرض المفتاح الكامل مرة واحدة عند إصداره ولا يمكن استعادته.
ملاحظة
Sending the key#
أرسل المفتاح في الترويسة X-API-Key مع كل طلب، ويُقبل أيضًا Authorization: Bearer. يؤدي غياب المفتاح إلى 401 API_KEY_REQUIRED، ويؤدي المفتاح المشوّه أو غير المعروف إلى 401 INVALID_API_KEY.
# Preferred
X-API-Key: esk_live_AbCdE12345_<40-character secret>
# Also accepted
Authorization: Bearer esk_live_AbCdE12345_<40-character secret>Issuing keys#
- 1بوابة الشركاء → مفاتيح API — أنشئ مفتاحًا جديدًا.
- 2امنحه اسمًا، ويمكنك اختياريًا تحديد مدة صلاحية (بين دقيقة واحدة و3 سنوات من الآن) وقائمة عناوين IP مسموح بها.
- 3انسخ المفتاح فورًا — فهو يُعرض مرة واحدة فقط — واحفظه في مدير أسرار أو متغير بيئة على الخادم.
يمكن لكل حساب افتراضيًا امتلاك ما يصل إلى 5 مفاتيح نشطة (مفاتيح غير ملغاة وغير منتهية الصلاحية).
Rotating keys#
يؤدي التدوير إلى إنشاء مفتاح جديد بالاسم والنطاقات وقائمة عناوين IP المسموح بها وتاريخ الانتهاء نفسها. يظل المفتاح القديم يعمل خلال فترة السماح التي تختارها (0–72 ساعة) ثم تنتهي صلاحيته — انشر المفتاح الجديد خلال هذه الفترة. فترة سماح 0 توقف المفتاح القديم فورًا.
ملاحظة
IP allowlist#
يمكن تقييد كل مفتاح بما يصل إلى 20 عنوان IPv4/IPv6 أو نطاق CIDR (مثل 203.0.113.10 و198.51.100.0/24). القائمة الفارغة تعني عدم وجود قيود، وتتلقى الطلبات الواردة من أي مكان آخر 403 IP_NOT_ALLOWED. استخدم عناوين IP الصادرة لخوادمك.
Revoking keys#
أبطِل المفتاح في البوابة فور تسريبه أو عند عدم الحاجة إليه. لا يتم تخزين المفاتيح مؤقتًا، لذا يُرفض الطلب التالي مباشرةً مع 401 KEY_REVOKED. في حالات الطوارئ، يمكن لـ esimoa إبطال المفاتيح أو تعليق الحساب، وتتلقى جميع مفاتيح الحساب المعلّق 403 PARTNER_SUSPENDED.
Member roles#
| الدور | الصلاحيات |
|---|---|
| OWNER | كل الميزات |
| ADMIN | إدارة المفاتيح والأعضاء |
| DEVELOPER | إدارة المفاتيح وتصفح المنتجات |
| VIEWER | للقراءة فقط |
يمكن فقط للأعضاء بدور OWNER وADMIN وDEVELOPER إصدار المفاتيح أو تدويرها أو إلغاؤها؛ ويمكن لجميع الأعضاء رؤية قائمة المفاتيح.