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

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

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

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": "pro_plus",
        "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 المصدر كما تراه الحافة. مع Cloudflare أمامها، هذا هو IP العميل الأصلي وليس IP لـ CF POP.
• الأسرار لا تُعاد أبدًا عبر GET.

POST /v1/keys — إنشاء

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

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

الجسم

الحقل	النوع	إلزامي	ملاحظات
type	platform | public	✅
name	string ≤ 100		تسمية حرة

الصلاحيات والخطة تُورَّث من المفتاح المنادي. للحصول على مفتاح بصلاحيات/خطة مختلفة تحتاج إلى مفتاح أُنشِئ من مسار الإدارة (يتولاه فريق الدعم).

الطلب

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" }'

الاستجابة 201

{
  "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 .... لمفتاح عام: 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..." } }

ما يحدث:

• api_v1_keys.status = 'revoked' يُضبط فورًا على الخادم.
• يُلحَق صف تدقيق في api_v1_key_events.
• ذاكرة KV على حافة Cloudflare تنتهي خلال ~60 ثانية؛ حتى ذلك الحين قد يستمر المفتاح في العمل لعمليات مخزَّنة. إن كان الإلغاء الفوري حرجًا، تواصل مع الدعم لتفريغ KV.

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

• مفتاح لكل بيئة — مفتاح staging ومفتاح production. لا تُشاركها.
• مفتاح لكل تكامل — مفتاح لـ Zapier، آخر لمزامنة CRM، آخر لخط التحليلات. أسهل في إلغاء تكامل واحد دون كسر الباقي.
• دوّر دوريًا — كل 90 يومًا لمفاتيح الإنتاج وتيرة معقولة.
• راجع last_used_at — المفاتيح غير المستخدمة منذ 30+ يومًا مرشّحة للإلغاء.
• لا ترسل سرًا بالبريد أبدًا — الصقه مرة في مدير الأسرار ولن تحتاجه ثانية.