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

مفاتيح API

تصادق مفاتيح API خوادمك. تحتاج نقاط النهاية هذه إلى مستخدم مسجل الدخول يملك الصلاحية apikeys:manage: لا يستطيع مفتاح API إنشاء المفاتيح أو تدويرها أو إلغاءها (403 api_key_not_allowed). يستخدم معظم الناس المطوّرون ← مفاتيح API في البوابة بدلا من ذلك (شرح خطوة بخطوة). ترسل الأمثلة رمز وصول المستخدم في Authorization: Bearer.

الحقل النوع الوصف
id string key_…
name string ما يستخدم المفتاح، مثل Production backend.
prefix string الجزء العام مثل sf_live_ab12cd34ef56، وليس السر أبدا.
mode string live أو test.
scopes string[] الصلاحيات التي يحملها المفتاح.
ipAllowlist string[] عناوين IP أو نطاقات CIDR المسموح لها باستخدامه. القائمة الفارغة تعني أي عنوان.
lastUsedAt string أو null
expiresAt string أو null
revokedAt string أو null
createdAt string
GET/v1/api-keysapikeys:manageللمستخدمين فقط

يعيد كل المفاتيح في صفحة واحدة (nextCursor: null).

نافذة طرفيّة
curl https://api.smsfabric.com/v1/api-keys \
-H "Authorization: Bearer $SMSFABRIC_USER_TOKEN"
{
"data": [
{
"id": "key_k5n8q1t4w7z0c3f6i9l2o5r8",
"name": "Production backend",
"prefix": "sf_live_ab12cd34ef56",
"mode": "live",
"scopes": ["messages:send", "messages:read"],
"ipAllowlist": ["203.0.113.0/24"],
"lastUsedAt": "2026-11-19T10:15:02.000Z",
"expiresAt": "2027-11-19T00:00:00.000Z",
"revokedAt": null,
"createdAt": "2026-11-19T09:00:00.000Z"
}
],
"nextCursor": null
}
POST/v1/api-keysapikeys:manageللمستخدمين فقط

يعيد 201 مع apiKey وsecret، أي المفتاح كاملا. لا يظهر السر إلا هذه المرة. يدعم Idempotency-Key. يُسجل في التدقيق باسم apikey.created.

حقل المحتوى النوع إلزامي الوصف القيود
name string نعم من 1 إلى 120 حرفا.
scopes string[] نعم الصلاحيات الممنوحة. فقط الصلاحيات التي يملكها دورك.
mode string نعم live يرسل رسائل حقيقية، وtest يستخدم بيئة الاختبار. live أو test.
expiresAt string لا وقت توقف المفتاح. ISO 8601 في المستقبل.
ipAllowlist string[] لا عناوين IP أو نطاقات CIDR المسموحة. حتى 50.
نافذة طرفيّة
curl https://api.smsfabric.com/v1/api-keys \
-H "Authorization: Bearer $SMSFABRIC_USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Staging", "mode": "test", "scopes": ["messages:send", "messages:read"]}'
{
"apiKey": {
"id": "key_l6o9r2u5x8a1d4g7j0m3p6s9",
"name": "Staging",
"prefix": "sf_test_xxxxxxxxxxxx",
"mode": "test",
"scopes": ["messages:send", "messages:read"],
"ipAllowlist": [],
"lastUsedAt": null,
"expiresAt": null,
"revokedAt": null,
"createdAt": "2026-11-19T13:00:00.000Z"
},
"secret": "sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
الخطأ متى
403 scope_escalation صلاحية لا يملكها دورك.
403 api_key_not_allowed استُدعي بمفتاح API.
400 validation_failed صلاحية غير معروفة، أو CIDR غير صالح، أو expiresAt في الماضي.
POST/v1/api-keys/:id/rotateapikeys:manageللمستخدمين فقط

يصدر سرا جديدا للمفتاح نفسه (المعرّف والبادئة والصلاحيات نفسها). يبقى السر القديم صالحا حتى previousSecretExpiresAt بعد 24 ساعة، لتنشر الجديد دون انقطاع. يعيد 200. يُسجل في التدقيق باسم apikey.rotated.

نافذة طرفيّة
curl -X POST https://api.smsfabric.com/v1/api-keys/key_k5n8q1t4w7z0c3f6i9l2o5r8/rotate \
-H "Authorization: Bearer $SMSFABRIC_USER_TOKEN"
{
"apiKey": { "id": "key_k5n8q1t4w7z0c3f6i9l2o5r8", "name": "Production backend", "prefix": "sf_live_ab12cd34ef56", "mode": "live" },
"secret": "sf_live_ab12cd34ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"previousSecretExpiresAt": "2026-11-20T13:05:00.000Z"
}

(اختُصر apiKey هنا.)

DELETE/v1/api-keys/:idapikeys:manageللمستخدمين فقط

تفشل الطلبات التي تستخدم المفتاح فورا مع 401 invalid_api_key. يعيد 204. يُسجل في التدقيق باسم apikey.revoked.

نافذة طرفيّة
curl -X DELETE https://api.smsfabric.com/v1/api-keys/key_k5n8q1t4w7z0c3f6i9l2o5r8 \
-H "Authorization: Bearer $SMSFABRIC_USER_TOKEN"