المصادقة
يُرفض كل طلب إلى https://api.smsfabric.com ما لم يحمل بيانات اعتماد. تستخدم شيفرة الخادم لديك مفتاح API، وتستخدم البوابة رمز مستخدم قصير العمر. تشرح هذه الصفحة الاثنين ومتى يُقبل كل منهما.
مفاتيح API
Section titled “مفاتيح 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"import { SMSFabric } from '@smsfabric/sdk';
// Reads SMSFABRIC_API_KEY when apiKey is omitted.const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sf.messages.list({ limit: 5 });console.log(page.data.length, 'messages');import osimport requests
session = requests.Session()session.headers.update({"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]})
res = session.get("https://api.smsfabric.com/v1/messages", params={"limit": 5}, timeout=30)res.raise_for_status()print(len(res.json()["data"]), "messages")<?php$ch = curl_init('https://api.smsfabric.com/v1/messages?limit=5');curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY')], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$page = json_decode(curl_exec($ch), true);echo count($page['data']) . " messages\n";الصلاحيات
Section titled “الصلاحيات”الصلاحيات نصوص تمثل أذونات. ينجح الطلب فقط إذا كان المفتاح يحمل كل صلاحية تحتاجها نقطة النهاية، وإلا يرد الخادم بالحالة 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". الأدوار وصلاحياتها مذكورة في الفريق في البوابة.
تقييد المفتاح
Section titled “تقييد المفتاح”عند إنشاء المفتاح يمكنك أيضا ضبط:
- تاريخ الانتهاء (
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، فتفشل الطلبات التي تستخدمه فورا.
رموز المستخدم
Section titled “رموز المستخدم”تسجّل البوابة الدخول عبر 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". يميّزها المرجع بعبارة للمستخدمين فقط.
أخطاء المصادقة
Section titled “أخطاء المصادقة”| الحالة | 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 |
المؤسسة موقوفة. | تواصل مع الدعم. |
القائمة الكاملة في الأخطاء.