مُراسِلواجهة Morasel البرمجية للمطوّرين
اقرأ وتصرف في السجلات نفسها التي يستخدمها فريقك — المحادثات، العملاء، المواعيد، الطلبات — برموز تحدد نطاقها، تقيّدها بعنوان IP، وتنهيها وفق جدولك الخاص.
لماذا يشكّل مفتاح بلا نطاق ولا تاريخ انتهاء خطراً
مفتاح API واحد بلا نطاق ولا قيد IP ولا تاريخ انتهاء خطر قائم: إن تسرّب، يستطيع من يجده قراءة أو تعديل كل ما تستطيعه مساحة العمل. معظم التكاملات تحتاج جزءاً بسيطاً من تلك الصلاحية، لمدة محددة، من أنظمة معروفة.
- رمز بصلاحية كاملة قد يقرأ أو يعدّل سجلات لم يحتجها التكامل قط.
- رمز بلا تاريخ انتهاء يبقى صالحاً بعد عام من انتهاء المشروع الذي أنشأه.
- رمز قابل للاستخدام من أي عنوان IP يمكن إعادة استخدامه من أي مكان يتسرب إليه نصه الصريح.
- مفتاح لا يمكن العثور على نصه الصريح مجدداً لا يمكن فحصه، بل إلغاؤه واستبداله فقط.
ما يسجّله مُراسِل لكل رمز
سجل رمز واحد لكل تكامل، ليرى المالك ما يستطيعه الرمز ومتى استُخدم آخر مرة دون سؤال الفريق الذي بناه.
- اسم الرمز
- التسمية التي يعطيها فريقك للرمز، مرتبطة بالتكامل الذي يخصّه.
- البادئة
- الأحرف الأولى من الرمز، تظهر بعد الإنشاء لتمييزه دون الحاجة للسر.
- النطاقات
- الكائنات والإجراءات التي يصل إليها الرمز؛ صلاحية القراءة افتراضية، وصلاحيات الكتابة تُمنح لكل كائن.
- قائمة IP المسموحة
- حتى 20 عنواناً يمكن استخدام الرمز منها؛ تركها فارغة يعني عدم وجود قيد IP.
- تاريخ الانتهاء
- تاريخ حتى 365 يوماً بعده يتوقف الرمز عن العمل.
- آخر استخدام
- آخر وقت تحقّق فيه طلب باستخدام هذا الرمز.
- نقطة الويب هوك
- الرابط ومفتاح التوقيع اللذان تسجّلهما من مساحة عملك لتكاملك.
من إنشاء رمز إلى تدويره
السر الصريح موجود مرة واحدة، عند الإنشاء. كل ما بعد ذلك يعمل على البادئة والنطاقات التي حددتها.
إنشاء رمز (المالك)
سمّه، اختر نطاقاته، وحدد اختيارياً قائمة IP مسموحة وتاريخ انتهاء حتى 365 يوماً.
انسخ السر مرة واحدة
يظهر الرمز الكامل مرة واحدة فقط. بعدها، لا يظهر على السجل سوى بادئته.
استدعِ الـ REST API برأس Bearer
وثّق الطلبات مقابل نقاط النهاية الموثقة؛ يُتحقق من كل استدعاء وفق نطاقات الرمز وقائمة IP المسموحة.
سجّل نقطة ويب هوك واحتفظ بمفتاح توقيعها
أضف رابط النقطة من مساحة عملك واحتفظ بمفتاح التوقيع الذي يمنحك إياه.
تدوير الرمز: أنشئ الخلف، ألغِ القديم
أصدر رمزاً جديداً قبل انتهاء صلاحية القديم أو تعرضه للاختراق، ثم ألغِ القديم بعد تفعيل الجديد.
ما يراه العميل
رسالة مُرسلة عبر الـ API تبدو تماماً كرسالة مُرسلة من مساحة العمل — لا طريقة للعميل ليميّز بينهما.
ما يراه فريقك
نشاط الرمز سجل، لا لغز في السجلات.
- نطاقات كل رمز وقائمة IP المسموحة وتاريخ الانتهاء وآخر استخدام، على سجل واحد.
- نقطة الويب هوك وخيار كشف أو تدوير مفتاح توقيعها.
- بادئة لتمييز الرمز في الحديث دون الحاجة إلى السر مجدداً أبداً.
- أحداث الإنشاء والإلغاء على سجل التدقيق نفسه لكل شيء آخر في مساحة العمل.
من يفعل ماذا
إصدار الصلاحية وإلغاؤها محصوران بمن يملك مساحة العمل، وكل تغيير مسجَّل.
- مالك مساحة العمل وحده يمكنه إنشاء رمز API أو إلغاءه.
- النطاقات افتراضياً للقراءة؛ صلاحية الكتابة على كائن تُمنح صراحة لا افتراضاً.
- قائمة IP المسموحة، إن وُجدت، تحصر الرمز في حتى 20 عنواناً معروفاً.
- كل إنشاء وإلغاء رمز مسجَّل في سجل التدقيق، بمن فعل ذلك ومتى.
ما لا يفعله مُراسِل
تُسجَّل نقاط الويب هوك بمفتاح توقيع من مساحة العمل. لا ينشر مُراسِل SDKs؛ وتُوثَّق الـ REST API كـ OpenAPI. تسجيل نقطة نهاية يحفظ عنوانها ومفتاح توقيعها لتكاملك.
ابدأ البناء على مُراسِل
أنشئ مساحة عمل، أصدر رمزاً محدد النطاق، واقرأ مرجع OpenAPI لنقاط النهاية التي تحتاجها.
أسئلة المطوّرين
كيف أحصل على رمز؟
ينشئه مالك مساحة العمل منها: اسم، نطاقات، واختيارياً قائمة IP مسموحة وتاريخ انتهاء. يظهر النص الصريح مرة واحدة عند الإنشاء.
ما النطاقات المتاحة؟
صلاحية القراءة افتراضية. صلاحية الكتابة على كائن محدد — المحادثات، العملاء، المواعيد، الطلبات — تُمنح لكل نطاق، فلا يصل الرمز إلا لما بُني من أجله.
ماذا تفعل قائمة IP المسموحة؟
تحصر الرمز في حتى 20 عنوان IP محدداً. اتركها فارغة ليعمل الرمز من أي مكان يُستخدم فيه السر؛ حدّدها وتُرفض الطلبات من عناوين أخرى.
كم يمكن أن يدوم الرمز؟
حتى 365 يوماً. بعد ذلك، أو في التاريخ الذي حددته، يتوقف عن التوثيق ويحتاج إلى استبدال.
أين مرجع الـ API؟
تُوثَّق الـ REST API كـ OpenAPI في /docs، وتغطي نقاط النهاية التي تصل إليها نطاقات الرمز.