تخطَّ إلى المحتوى

المصادقة

يُرفض كل طلب إلى https://api.smsfabric.com ما لم يحمل بيانات اعتماد. تستخدم شيفرة الخادم لديك مفتاح API، وتستخدم البوابة رمز مستخدم قصير العمر. تشرح هذه الصفحة الاثنين ومتى يُقبل كل منهما.

ينتمي مفتاح API إلى مؤسسة واحدة ويحمل مجموعة ثابتة من الصلاحيات. أرسله في الترويسة X-Api-Key:

X-Api-Key: sf_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

يتكون المفتاح من ثلاثة أجزاء تفصل بينها شرطة سفلية:

الجزء مثال المعنى
الوضع sf_live_ أو sf_test_ live يرسل رسائل حقيقية عبر هواتفك. test يعمل في بيئة الاختبار ولا يلمس أي هاتف.
البادئة ab12cd34ef56 12 حرفا صغيرا ورقما. تعرّف المفتاح وتظهر في البوابة وفي GET /v1/api-keys.
السر 32 حرفا ورقما يظهر مرة واحدة عند إنشاء المفتاح أو تدويره. لا تحفظ SMSFabric إلا تجزئة SHA-256 منه مع ملح سري.

أنشئ المفاتيح في البوابة من المطوّرون ← مفاتيح API (انظر مفاتيح API في البوابة)، أو عبر POST /v1/api-keys وأنت مسجل الدخول. احفظ المفتاح في متغير بيئة أو مدير أسرار، ولا تضعه أبدا في نظام التحكم بالإصدارات.

نافذة طرفيّة
export SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
curl https://api.smsfabric.com/v1/messages?limit=5 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

الصلاحيات نصوص تمثل أذونات. ينجح الطلب فقط إذا كان المفتاح يحمل كل صلاحية تحتاجها نقطة النهاية، وإلا يرد الخادم بالحالة 403 مع code: "missing_permission". يعرض كل مدخل في المرجع الصلاحية المطلوبة بجانب المسار.

الصلاحية تسمح للمفتاح بأن
messages:send يرسل رسائل (POST /v1/messages). يحتاجها بدء الحملة أيضا.
messages:read يقرأ الرسائل والإحصاءات.
logs:export ينزّل ملفات CSV المصدّرة.
devices:read / devices:manage يقرأ الأجهزة والشرائح والمجموعات / يقرن الأجهزة ويعيد تسميتها ويفصلها ويضبطها.
contacts:read / contacts:manage يقرأ / يعدّل جهات الاتصال والمجموعات وعمليات الاستيراد.
campaigns:read / campaigns:manage يقرأ / يعدّل القوالب والحملات.
blacklist:manage يقرأ القائمة السوداء ويعدّلها.
verify:send / verify:check يرسل رموز التحقق / يتحقق منها ويقرأ عمليات التحقق.
webhooks:manage ينشئ نقاط نهاية webhook ويديرها.
settings:manage يغيّر تفضيلات الإرسال.
audit:read يقرأ سجل التدقيق.

امنح كل مفتاح ما يحتاجه من يستخدمه فقط. الخادم الذي يرسل رموز OTP يحتاج verify:send وverify:check لا أكثر.

لا يمكنك منح صلاحيات لا يملكها دورك أنت. طلب أكثر من ذلك يعيد 403 مع code: "scope_escalation". الأدوار وصلاحياتها مذكورة في الفريق في البوابة.

عند إنشاء المفتاح يمكنك أيضا ضبط:

  • تاريخ الانتهاء (expiresAt). بعده تفشل الطلبات مع 401 api_key_expired.
  • قائمة عناوين IP المسموحة (ipAllowlist): حتى 50 عنوانا أو نطاق CIDR. يفشل الطلب من أي عنوان آخر مع 403 ip_not_allowed.

دوّر المفتاح عبر POST /v1/api-keys/:id/rotate. تحصل على سر جديد، ويبقى القديم صالحا 24 ساعة لتنشر التغيير دون انقطاع. ألغِ المفتاح عبر DELETE /v1/api-keys/:id، فتفشل الطلبات التي تستخدمه فورا.

تسجّل البوابة الدخول عبر POST /v1/auth/login وترسل رمز وصول صالحا 15 دقيقة في Authorization: Bearer <token>. نادرا ما تحتاج إلى هذا في شيفرتك. لكن بعض نقاط النهاية تقبل فقط مستخدما مسجل الدخول، كي لا يستطيع مفتاح مسرّب توسيع صلاحياته:

نقطة النهاية السبب
GET /v1/api-keys، POST /v1/api-keys، POST /v1/api-keys/:id/rotate، DELETE /v1/api-keys/:id لا يجوز لمفتاح أن ينشئ مفاتيح أو يلغيها.
PATCH /v1/org، GET /v1/org/members، POST /v1/org/invitations وباقي نقاط نهاية الفريق تغييرات الفريق والمؤسسة.
PUT /v1/verify/settings الدول المسموحة في خدمة التحقق.
GET /v1/auth/sessions، POST /v1/auth/2fa/setup وباقي نقاط نهاية تسجيل الدخول الجلسات والمصادقة الثنائية تخص شخصا بعينه.

إذا استُخدم مفتاح API مع إحداها يعود 403 مع code: "api_key_not_allowed". يميّزها المرجع بعبارة للمستخدمين فقط.

الحالة code ما حدث ما العمل
401 unauthorized لم تُرسل بيانات اعتماد. أضف الترويسة X-Api-Key.
401 invalid_api_key المفتاح غير صالح الصيغة أو غير معروف أو ملغى. تحقق من وجود مسافات أو قيمة مقطوعة، وأنشئ مفتاحا جديدا إن كان ملغى.
401 api_key_expired انقضى expiresAt الخاص بالمفتاح. أنشئ مفتاحا أو دوّره.
403 ip_not_allowed عنوان IP للطالب ليس في قائمة المفتاح. أضف العنوان، أو اتصل من خادم مسموح.
403 missing_permission ينقص المفتاح صلاحية تحتاجها نقطة النهاية. أنشئ مفتاحا بهذه الصلاحية.
403 api_key_not_allowed نقطة النهاية للمستخدمين المسجلين فقط. نفّذ العملية من البوابة.
403 tenant_suspended المؤسسة موقوفة. تواصل مع الدعم.

القائمة الكاملة في الأخطاء.