تخط وانتقل إلى المحتوى الرئيسي

المفاتيح (مفاتيحك الخاصة)

أنشئ، اعرض، وألغِ مفاتيح الواجهة البرمجية لمتجرك. مفاتيح المنصة (Bearer) والمفاتيح العامة (HMAC).

بقلم: Support

أدر مفاتيح الواجهة البرمجية لـ متجرك. كل عمليات المفاتيح تتطلب مفتاح منصة (المفتاح العام لا يستطيع إنشاء مفاتيح أخرى — بقصد التصميم).

انتباه: المفتاح المُنشَأ عبر الواجهة البرمجية يصبح فعّالًا فورًا. لا يوجد تأكيد بالبريد ولا موافقة من مشرف. إن أنشأت مفتاحًا بصلاحيات واسعة وسرّبته، فإن المسرّب يمكنه التصرف بكامل صلاحيات هذا المفتاح حتى تستخدم DELETE. أبقِ الأسرار خارج المستودعات والشاشات المشتركة.

الحصول على مفتاحك الأول

الواجهة البرمجية حصرية لخطة Enterprise: لا تُصدَر المفاتيح إلا للمتاجر ذات خطة Enterprise سارية، وإنشاء مفتاح لأي خطة أخرى يفشل. أنشئ مفتاحك الأول من لوحة التحكم عبر الإعدادات ← واجهة API (/dashboard/api) — متاحة لمالك المتجر، ويظهر السر مرة واحدة عند الإنشاء. ويمكنك أيضًا إنشاء المفاتيح وتدويرها عبر النقاط أدناه. يمكن للمتجر الاحتفاظ بـ 3 مفاتيح نشطة كحد أقصى (عبر جميع طرق الإنشاء)؛ ألغِ مفتاحًا لتحرير مكانه.

كما أن الواجهة البرمجية حاليًا مقيَّدة ببرنامج تجريبي (pilot). المفاتيح التي تُنشئها ترث تسجيل مفتاحك في البرنامج التجريبي فتعمل — أما أي مفتاح أُنشئ خارجه فيُرجع 403 forbidden ("API is in pilot mode; key not enrolled") على كل نداء.

GET /v1/keys

اسرد مفاتيح متجرك (يستثنى المُلغَى؛ المفاتيح المُلغَاة محفوظة في سجل التدقيق لكنها مخفية عن هذه القائمة).

المصادقة: مفتاح منصة.

الاستجابة 200

{
  "data": {
    "items": [
      {
        "key_id":          "dzpk_live_c741d949613f8f",
        "type":            "platform",
        "name":            "production-server-1",
        "scopes":          ["store:read", "products:read", "orders:read", "orders:write"],
        "rate_limit_tier": "enterprise",
        "pilot":           true,
        "status":          "active",
        "last_used_at":    "2026-04-30 19:35:49",
        "last_used_ip":    "203.0.113.42",
        "created_at":      "2026-04-30 19:27:55",
        "expires_at":      null
      }
    ]
  }
}

ملاحظات: - last_used_at يُحدَّث مع كل نداء موثَّق (كتابة best-effort — قد تتأخر بضع ثوانٍ). - last_used_ip هو عنوان IP المصدر للمنادي كما تراه الواجهة البرمجية — أي IP العميل الأصلي، لا عنوان وسيط. - الأسرار لا تُعاد أبدًا عبر GET. - expires_at دائمًا null — لا شيء يضبطه والمفاتيح لا تنتهي تلقائيًا. ألغِها صراحةً. - المفاتيح بحالة status: "suspended" تظهر في هذه القائمة؛ المخفية هي المُلغَاة فقط. - key_id دائمًا 24 حرفًا بالضبط بما في ذلك البادئة dzpk_live_ / dzpub_live_.

POST /v1/keys — إنشاء

أنشئ مفتاحًا جديدًا. السر يُعاد مرة واحدة فقط — احفظه فورًا.

المصادقة: مفتاح منصة. يتطلب Idempotency-Key.

الجسم

الحقل

النوع

إلزامي

ملاحظات

type

platform | public

الافتراضي platform — إغفاله يُنشئ مفتاح منصة بصلاحية كاملة، فأرسله دائمًا صراحةً. والقيمة خارج المجموعة تُرجع 400

name

string ≤ 100

تسمية حرة. الافتراضي default، ويُقتطع قسرًا عند 100 حرف دون أي خطأ

الخطة (tier) والتسجيل في البرنامج التجريبي يُورَّثان من المفتاح المنادي. أما الصلاحيات فلا. كل مفتاح يُنشأ عبر POST /v1/keys يحصل على مجموعة الصلاحيات الافتراضية الكاملة لنوعه — فمفاتيح المنصة تحصل على store:read/store:write وproducts:read/products:write وorders:read/orders:write وcustomers:read وlanding_pages:read/landing_pages:write وwebhooks:read/webhooks:write وusage:read؛ والمفاتيح العامة تحصل على signups:write وevents:write. أي أن مفتاحًا ضيّق الصلاحيات يستطيع إنشاء مفتاح كامل الصلاحيات: عامل أي مفتاح منصة على أنه يعادل وصولًا كاملًا للمتجر، وتواصل مع الدعم إن أردت مفتاحًا بصلاحيات مخفَّضة.

الطلب

curl -X POST 'https://api.dzbuild.app/v1/keys' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "type": "platform", "name": "ci-deploy-key" }'

الاستجابة 200

إنشاء المفتاح يُرجع HTTP 200 وليس 201 — تحقّق من data.key_id بدل رمز الحالة.

{
  "data": {
    "key_id":         "dzpk_live_a3f9...",
    "bearer_token":   "dzpk_live_a3f9..........73ad…",
    "signing_secret": "185c4b5216c9d3f713a4ac7842d4664b75fa287b4aa4105cc27f933d7385a740",
    "note":           "Save these now — secrets are not retrievable."
  }
}

لمفتاح منصة: bearer_token هو ما تضعه في Authorization: Bearer ... — وصيغته {key_id}.{سر hex من 48 حرفًا}. لمفتاح عام: bearer_token يكون null وتستخدم signing_secret لحساب تواقيع HMAC (انظر المصادقة).

DELETE /v1/keys/{key_id} — إلغاء

المصادقة: مفتاح منصة. يتطلب Idempotency-Key.

curl -X DELETE 'https://api.dzbuild.app/v1/keys/dzpk_live_a3f9...' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: revoke-a3f9"

الاستجابة:

{ "data": { "revoked": true, "key_id": "dzpk_live_a3f9..." } }

ما يحدث:

  • تتحوّل حالة المفتاح إلى revoked فورًا ويختفي من GET /v1/keys.

  • يُسجَّل الإلغاء في سجل تدقيق المفاتيح الخاص بك.

  • قد يستغرق انتشار الإلغاء حتى ~60 ثانية؛ حتى ذلك الحين قد ينجح المفتاح في بعض النداءات. إن كان القطع الفوري حرجًا، تواصل مع الدعم.

أفضل الممارسات

  • مفتاح لكل بيئة — مفتاح staging ومفتاح production. لا تُشاركها.

  • مفتاح لكل تكامل — مفتاح لـ Zapier، آخر لمزامنة CRM، آخر لخط التحليلات. أسهل في إلغاء تكامل واحد دون كسر الباقي.

  • دوّر دوريًا — كل 90 يومًا لمفاتيح الإنتاج وتيرة معقولة.

  • راجع last_used_at — المفاتيح غير المستخدمة منذ 30+ يومًا مرشّحة للإلغاء.

  • لا ترسل سرًا بالبريد أبدًا — الصقه مرة في مدير الأسرار ولن تحتاجه ثانية.

المقالات ذات الصلة
هل أجاب هذا عن سؤالك؟