على مستوى الحساب
يوصل كل مشاريع الحساب. خلّ حقل المشروع فاضي وقت السكّ. مناسب لأداة داخلية تشتغل على أكثر من مشروع.
مفاتيح الـAPI هي اللي تصادق كل نداء على الـREST API وعلى خادم MCP. كل مفتاح له اسم ونطاق وسرّ يظهر لك مرّة وحدة بس. السرّ ما ينحفظ عندنا إلا كبصمة غير قابلة للعكس: نقدر نتحقّق من المفتاح، لكن ما نقدر نرجّعه لك أبداً.
هذي المفاتيح شي ثاني غير توكنات الودجت، وغير الاعتمادات اللي تربط متتبّعات المهام. وظيفتها الوحيدة: تفتح الـREST API.
المفتاح يُسكّ على واحد من نطاقين، والنطاق يُفرَض على كل طلب:
على مستوى الحساب
يوصل كل مشاريع الحساب. خلّ حقل المشروع فاضي وقت السكّ. مناسب لأداة داخلية تشتغل على أكثر من مشروع.
على مشروع واحد
يوصل مشروع واحد بس ولا شي غيره. اختر المشروع وقت السكّ. الأفضل تبدأ من هنا: الضرر أضيق لو تسرّب.
أي طلب لمشروع خارج نطاق المفتاح، أو في حساب ثاني، يُرفض بـ403 وما يتسرّب منه شي. الوصول بين الحسابات مستحيل.
افتح مفاتيح API باللوحة (/api-keys).
اعطِ المفتاح اسم (لين 100 حرف)، شي يعرّفك وين مستخدمه، مثل support-inbox-importer.
اختر النطاق. ولو اخترت مشروع، حدّد المشروع اللي ينحصر فيه. (مفتاح مشروع بدون مشروع يُرفض، وبيطلب منك تختار.)
أنشئ المفتاح. السرّ الكامل يظهر مرّة وحدة. انسخه الحين.
صيغة السرّ: md_live_ وبعدها 40 محرف:
md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxبعد الإنشاء، القائمة تعرض بيانات وصفية بس، لا السرّ ولا جزء منه:
| الحقل | الوصف |
|---|---|
| الاسم | التسمية اللي حطّيتها. |
| النطاق | «الحساب»، أو اسم المشروع لو المفتاح على مشروع واحد. |
| البادئة | أول 12 محرف (md_live_…)، عشان تميّز المفتاح بنظرة. |
| أنشأه | مين سكّه. يطلع «عضو سابق» لو انحذف الشخص من الحساب. |
| آخر استخدام | آخر مرّة صادق فيها المفتاح طلب، ويُكتب مع كل نداء ناجح. |
| إجراءات | زرّ السحب، طالما المفتاح شغّال. وبعد ما تسحبه يصير مكانه كلمة «مُبطَل»: المفتاح يبقى بالقائمة كسجلّ إنه كان موجود. |
عمود أنشأه هو اللي تحتاجه يوم يطلع زميل من الفريق: يقول لك أي اعتماد لا يزال بيده. وآخر استخدام يبيّن لك المفاتيح اللي ما أحد يستعملها (تقدر تسحبها بأمان)، أو مفتاح صار نشط فجأة وما المفروض يكون.
أرسل السرّ مع كل طلب، إمّا كـbearer token أو في ترويسة X-Api-Key:
Authorization: Bearer md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxX-Api-Key: md_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxمفتاح ناقص يرجع 401 API key required.؛ ومفتاح مجهول أو مسحوب يرجع 401 Invalid or revoked API key. شوف مرجع الـREST API للنقاط وجدول الأخطاء كامل.
المفتاح مو منفصل عن الشخص اللي سكّه. uMarker تعيد فحص الاثنين مع كل طلب، وتردّ 403 برسالة تسمّي السبب في الحالات التالية:
حذف العضو نهائياً شي مختلف: يسحب مفاتيحه على طول وبلا رجعة.
الـAPI للمطوّرين محسوب لكل مفتاح، مو لكل IP: كل مفتاح له حصّته لحاله بدل حصّة وحدة يتقاسمها كل اللي خلف نفس العنوان، ومفتاح واحد يسيء الاستخدام تقدر تعزله لحاله. السقوف الافتراضية 300 طلب بالدقيقة لكل مفتاح، وفوقها سقف أوسع 1200 بالدقيقة لكل عنوان IP — وهذا السقف الثاني مشترك، فالمفاتيح اللي تنادي من نفس عنوان الخروج تتلاقى عنده.
تجاوز الحدّ يرجع 429 Too Many Requests ومعه ترويسة Retry-After تقول لك كم ثانية تنتظر:
HTTP/1.1 429 Too Many RequestsRetry-After: 30صمّم عميلك يتراجع عند 429 بدل ما يعيد المحاولة بشراسة. وللقراءات الكبيرة، قسّم النتائج على صفحات (per_page لين 100) بدل ما تضرب النقطة بلا توقّف.
اسحب المفتاح أول ما تستغني عنه أو تشكّ إنه تسرّب. السحب فوري: الطلب اللي بعده يُرفض بـ401.
من صفحة مفاتيح API، دوّر المفتاح بالاسم أو بالبادئة.
اسحبه. uMarker تعلّمه مسحوباً وتأكّد لك.
أي نداء بعدها بنفس المفتاح يفشل مُغلقاً بـ401 Invalid or revoked API key.
ما فيه تراجع عن السحب، ولا تدوير في المكان. عشان تدوّر مفتاح: اسكّ واحد جديد، انشره على عميلك، وبعد ما ينتقل الترافيك اسحب القديم.
شوف نظرة عامة على الأمان والخصوصية وعزل الحسابات عشان تعرف وين تقع هذي الضمانات من المنصّة كلها.