مفاتيح API
تصادق مفاتيح API خوادمك. تحتاج نقاط النهاية هذه إلى مستخدم مسجل الدخول يملك الصلاحية apikeys:manage: لا يستطيع مفتاح API إنشاء المفاتيح أو تدويرها أو إلغاءها (403 api_key_not_allowed). يستخدم معظم الناس المطوّرون ← مفاتيح API في البوابة بدلا من ذلك (شرح خطوة بخطوة). ترسل الأمثلة رمز وصول المستخدم في Authorization: Bearer.
كائن مفتاح API
Section titled “كائن مفتاح API”| الحقل | النوع | الوصف |
|---|---|---|
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 |
عرض المفاتيح
Section titled “عرض المفاتيح”/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}إنشاء مفتاح
Section titled “إنشاء مفتاح”/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 في الماضي. |
تدوير مفتاح
Section titled “تدوير مفتاح”/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 هنا.)
إلغاء مفتاح
Section titled “إلغاء مفتاح”/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"