مفاتيح API
يدير sms.apiKeys المفاتيح التي تستخدمها خوادمك. تنشئ معظم الفرق المفاتيح من البوابة عبر المطورون ← مفاتيح API (الشرح خطوة بخطوة)؛ استخدم هذه الدوال لأتمتة التدوير أو لإنشاء المفاتيح من أداة إدارية.
لماذا تحتاج إلى رمز وصول
Section titled “لماذا تحتاج إلى رمز وصول”لا يستطيع مفتاح API إنشاء مفاتيح API أو تدويرها أو إبطالها. لو استطاع ذلك، لأمكن لمفتاح مسرب أن ينشئ مفاتيح بنطاقات أوسع ويبقى فاعلًا بعد إبطاله. تقبل نقاط النهاية هذه رمز وصول لمستخدم مسجل الدخول فقط، ويجب أن يملك دور المستخدم apikeys:manage (يملكه المالك والمسؤول والمطور).
import { SMSFabric } from '@smsfabric/sdk';
// A user access token, not an API key. See "User tokens" in the Authentication guide.export const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });رمز الوصول صالح 15 دقيقة. احصل عليه بتسجيل الدخول كما في رموز المستخدم، واستخدمه للمهمة، ولا تخزنه.
| الدالة | طلب HTTP | القيمة المعادة |
|---|---|---|
list() |
GET /v1/api-keys |
ApiKey[] |
create(params, options?) |
POST /v1/api-keys |
CreatedApiKey |
rotate(id) |
POST /v1/api-keys/:id/rotate |
RotatedApiKey |
revoke(id) |
DELETE /v1/api-keys/:id |
void |
كل المفاتيح مع prefix وname وmode وscopes وقائمة عناوين IP المسموح بها وlastUsedAt وexpiresAt وrevokedAt. لا يعاد السر أبدًا.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });const ninetyDaysAgo = Date.now() - 90 * 24 * 60 * 60 * 1000;
for (const key of await admin.apiKeys.list()) { const unused = !key.lastUsedAt || Date.parse(key.lastUsedAt) < ninetyDaysAgo; if (!key.revokedAt && unused) console.log(`${key.name} (${key.prefix}) has not been used for 90 days`);}create
Section titled “create”تنشئ مفتاحًا. امنحه النطاقات التي يحتاجها فقط، مع تاريخ انتهاء وقائمة عناوين IP مسموح بها حيثما أمكن.
| المعامل | النوع | ملاحظات |
|---|---|---|
name |
string |
يظهر في البوابة وسجل التدقيق. |
scopes |
Permission[] |
مثل ['messages:send', 'messages:read']. |
mode |
'live' | 'test' |
مفتاح test يرسل عبر بيئة الاختبار، ولا يصل شيء إلى هاتف حقيقي. |
expiresAt |
Date | string |
اختياري. |
ipAllowlist |
string[] |
عناوين IP أو نطاقات CIDR مسموح لها باستخدام المفتاح، اختياري. |
تحتوي النتيجة على apiKey (المفتاح المحفوظ) وsecret (القيمة الكاملة sf_live_… أو sf_test_…)، ولا تعاد إلا هذه المرة.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
const { apiKey, secret } = await admin.apiKeys.create({ name: 'Checkout service', scopes: ['verify:send', 'verify:check'], mode: 'live', expiresAt: new Date('2027-06-30T00:00:00Z'), ipAllowlist: ['203.0.113.0/24'],});
console.log(apiKey.id, apiKey.prefix);// Write `secret` straight to your secret manager. Never log it.void secret;rotate
Section titled “rotate”تصدر سرًا جديدًا للمفتاح نفسه. يبقى السر القديم صالحًا حتى previousSecretExpiresAt بعد 24 ساعة، فتنشر السر الجديد دون انقطاع. لا تعاد محاولة rotate تلقائيًا.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
const rotated = await admin.apiKeys.rotate('key_…');console.log('Deploy the new secret before', rotated.previousSecretExpiresAt);void rotated.secret; // store it, don't print itrevoke
Section titled “revoke”تبطل المفتاح فورًا. الطلبات التي تستخدمه تفشل بعدها بـ 401.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
await admin.apiKeys.revoke('key_…');إنشاء المفاتيح وتدويرها وإبطالها يسجل في سجل التدقيق.