إدارة مفاتيح API

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

مفتاح API الخاص بالقنوات

ده المفتاح اللي بيوثّق POST /api/sms/send وPOST /api/whatsapp/send وPOST /api/email/send، ونقاط النهاية المقابلة للاستعلام GET /api/get/{channel}/{id?}. بيتبعت عبر هيدر Api-key (أو بديل query/body)، مش كـ Bearer token.

فين تلاقيه: صفحة API key في حسابك بلوحة التحكم، تحت إعدادات الحساب.

إيه اللي يقدر يعمله: إرسال رسائل على أى قناة عندك بوابة متصلة بيها في حسابك، واستهلاك حصة الإرسال بتاعة حسابك. أى حد عنده المفتاح ده يقدر يبعت بالنيابة عنك ويستهلك رصيدك — تعامل معاه بالظبط زي كلمة المرور.

مفتاح AI Pool

ده بيانات دخول منفصلة بتُستخدم بس لـ AI Gateway (POST /api/ai/v1/chat/completions، GET /api/ai/v1/models). بيتبعت كـ Bearer token عادي:

Authorization: Bearer <ai-pool-key>

فين تلاقيه: قسم AI Pool / AI Gateway في لوحة التحكم — شاشة منفصلة عن مفتاح API الخاص بالقنوات.

أفضل الممارسات لحماية مفاتيح API

• لا تُضمّن أيًا من المفتاحين في تطبيقات العميل (Client-side). يجب استخدام كلٍ من مفتاح API الخاص بالقنوات ومفتاح AI Pool من خلال الخادم (Back-end) فقط. فأي مفتاح يُدرج داخل تطبيقات الهواتف المحمولة، أو حزم الواجهة الأمامية (Front-end Bundles)، أو أي كود يعمل في متصفح المستخدم، يُعد مكشوفًا ويمكن لأي شخص الوصول إليه.
• جدّد المفتاح فورًا عند الاشتباه في تسربه. إذا نُشر المفتاح في مستودع كود عام، أو أُدرج في مستند مشترك، أو ظهر في سجلات غير مخصصة لذلك، أو تمت مشاركته مع شخص لم يعد بحاجة إليه، فيجب تجديده مباشرةً. ويؤدي تجديد المفتاح إلى إلغاء صلاحية المفتاح السابق فورًا، لذا احرص على تحديث جميع عمليات التكامل التي تستخدمه قبل التجديد، أو خطط لفترة انتقالية قصيرة لتجنب انقطاع الخدمة.
• تعامل مع مفاتيح API كما تتعامل مع كلمات المرور. لا ترسلها عبر قنوات اتصال غير مشفرة، وتجنب مشاركتها في أدوات المحادثة أو أنظمة التذاكر متى أمكن، ولا تستخدم المفتاح نفسه خارج الأنظمة التي خُصص لها.
• احصر الوصول إلى المفاتيح في الأنظمة التي تحتاج إليها فقط. حتى إذا لم تكن المنصة توفر مستويات إضافية لتقسيم الصلاحيات، فمن الأفضل تحديد الأنظمة التي تحتاج بالفعل إلى استخدام كل مفتاح. فإذا كانت لديك عدة أنظمة تتكامل مع مرسال، مثل موقع إلكتروني، أو خادم لتطبيق جوّال، أو أداة داخلية، فاحرص على منح كل نظام الوصول إلى المفتاح الذي يحتاجه فقط، وتجنب تعريض المفاتيح لأنظمة لا تتطلب استخدامها.

الخطوات التالية

• المصادقة — تفاصيل الطلب والاستجابة الكاملة لنوعى المفاتيح.
• نظرة عامة على أمان المنصة — الصورة الأشمل لحماية الحساب والبيانات.