تخطَّ إلى المحتوى
تسجيل الدخولاطلب حساب

مفاتيح الـAPI وحدود الطلبات

مفاتيح الـAPI هي اللي تصادق كل نداء على الـREST API وعلى خادم MCP. كل مفتاح له اسم ونطاق وسرّ يظهر لك مرّة وحدة بس. السرّ ما ينحفظ عندنا إلا كبصمة غير قابلة للعكس: نقدر نتحقّق من المفتاح، لكن ما نقدر نرجّعه لك أبداً.

هذي المفاتيح شي ثاني غير توكنات الودجت، وغير الاعتمادات اللي تربط متتبّعات المهام. وظيفتها الوحيدة: تفتح الـREST API.

المفتاح يُسكّ على واحد من نطاقين، والنطاق يُفرَض على كل طلب:

على مستوى الحساب

يوصل كل مشاريع الحساب. خلّ حقل المشروع فاضي وقت السكّ. مناسب لأداة داخلية تشتغل على أكثر من مشروع.

على مشروع واحد

يوصل مشروع واحد بس ولا شي غيره. اختر المشروع وقت السكّ. الأفضل تبدأ من هنا: الضرر أضيق لو تسرّب.

أي طلب لمشروع خارج نطاق المفتاح، أو في حساب ثاني، يُرفض بـ403 وما يتسرّب منه شي. الوصول بين الحسابات مستحيل.

  1. افتح مفاتيح API باللوحة (/api-keys).

  2. اعطِ المفتاح اسم (لين 100 حرف)، شي يعرّفك وين مستخدمه، مثل support-inbox-importer.

  3. اختر النطاق. ولو اخترت مشروع، حدّد المشروع اللي ينحصر فيه. (مفتاح مشروع بدون مشروع يُرفض، وبيطلب منك تختار.)

  4. أنشئ المفتاح. السرّ الكامل يظهر مرّة وحدة. انسخه الحين.

صيغة السرّ: md_live_ وبعدها 40 محرف:

md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

بعد الإنشاء، القائمة تعرض بيانات وصفية بس، لا السرّ ولا جزء منه:

الحقل الوصف
الاسم التسمية اللي حطّيتها.
النطاق «الحساب»، أو اسم المشروع لو المفتاح على مشروع واحد.
البادئة أول 12 محرف (md_live_…)، عشان تميّز المفتاح بنظرة.
أنشأه مين سكّه. يطلع «عضو سابق» لو انحذف الشخص من الحساب.
آخر استخدام آخر مرّة صادق فيها المفتاح طلب، ويُكتب مع كل نداء ناجح.
إجراءات زرّ السحب، طالما المفتاح شغّال. وبعد ما تسحبه يصير مكانه كلمة «مُبطَل»: المفتاح يبقى بالقائمة كسجلّ إنه كان موجود.

عمود أنشأه هو اللي تحتاجه يوم يطلع زميل من الفريق: يقول لك أي اعتماد لا يزال بيده. وآخر استخدام يبيّن لك المفاتيح اللي ما أحد يستعملها (تقدر تسحبها بأمان)، أو مفتاح صار نشط فجأة وما المفروض يكون.

أرسل السرّ مع كل طلب، إمّا كـbearer token أو في ترويسة X-Api-Key:

Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

مفتاح ناقص يرجع 401 API key required.؛ ومفتاح مجهول أو مسحوب يرجع 401 Invalid or revoked API key. شوف مرجع الـREST API للنقاط وجدول الأخطاء كامل.

المفتاح مو منفصل عن الشخص اللي سكّه. uMarker تعيد فحص الاثنين مع كل طلب، وتردّ 403 برسالة تسمّي السبب في الحالات التالية:

  • الحساب معلَّق من المنصّة.
  • اللي سكّ المفتاح معلَّق أو محظور. التعليق هو الرافعة القابلة للعكس عندنا: ترجّع الشخص فترجع مفاتيحه، وهذا شي ما كان السحب يقدر يتراجع عنه.
  • مقعد اللي سكّه متوقّف لأن الباقة ما عادت تغطّي كل الفريق. فرّغ مقعد أو رقّي الباقة، ونفس المفتاح يكمل.
  • الباقة ما عادت تشمل الوصول للـAPI (فوق).

حذف العضو نهائياً شي مختلف: يسحب مفاتيحه على طول وبلا رجعة.

الـAPI للمطوّرين محسوب لكل مفتاح، مو لكل IP: كل مفتاح له حصّته لحاله بدل حصّة وحدة يتقاسمها كل اللي خلف نفس العنوان، ومفتاح واحد يسيء الاستخدام تقدر تعزله لحاله. السقوف الافتراضية 300 طلب بالدقيقة لكل مفتاح، وفوقها سقف أوسع 1200 بالدقيقة لكل عنوان IP — وهذا السقف الثاني مشترك، فالمفاتيح اللي تنادي من نفس عنوان الخروج تتلاقى عنده.

تجاوز الحدّ يرجع 429 Too Many Requests ومعه ترويسة Retry-After تقول لك كم ثانية تنتظر:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

صمّم عميلك يتراجع عند 429 بدل ما يعيد المحاولة بشراسة. وللقراءات الكبيرة، قسّم النتائج على صفحات (per_page لين 100) بدل ما تضرب النقطة بلا توقّف.

اسحب المفتاح أول ما تستغني عنه أو تشكّ إنه تسرّب. السحب فوري: الطلب اللي بعده يُرفض بـ401.

  1. من صفحة مفاتيح API، دوّر المفتاح بالاسم أو بالبادئة.

  2. اسحبه. uMarker تعلّمه مسحوباً وتأكّد لك.

  3. أي نداء بعدها بنفس المفتاح يفشل مُغلقاً بـ401 Invalid or revoked API key.

ما فيه تراجع عن السحب، ولا تدوير في المكان. عشان تدوّر مفتاح: اسكّ واحد جديد، انشره على عميلك، وبعد ما ينتقل الترافيك اسحب القديم.

النموذج الأمني باختصار

Section titled “النموذج الأمني باختصار”
  • السرّ ينحفظ كبصمة SHA-256 غير قابلة للعكس، وما يُسترجَع نصّاً من أي واجهة ولا استجابة API ولا سجلّ.
  • النطاق والحساب يُعاد فحصهما على الخادم مع كل طلب؛ ما فيه ثقة بالعميل.
  • السحب يسري على النداء التالي، وما فيه فترة سماح.
  • كل سكّ وكل سحب يُكتب في سجلّ التدقيق — وهو سجلّ داخلي عند uMarker، يعرّف المفتاح بالمعرّف (id) مو بالاسم اللي سمّيته أنت. وما هو معروض في لوحتك، وهذي المدخلات تُحفظ 30 يوم.
  • مفاتيح الـAPI سطح مصادقة مستقلّ عن توكنات الودجت؛ ما يتقاطعون أبداً.

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