API keys
sms.apiKeys manages the keys your servers use. Most teams create keys in the portal under Developers → API keys (walkthrough); use these methods to automate rotation or to provision keys from an admin tool.
Why it needs an access token
Section titled “Why it needs an access token”An API key cannot create, rotate or revoke API keys. If it could, a leaked key could mint new keys with wider scopes and outlive its own revocation. These endpoints accept only a signed-in user’s access token, and the user’s role needs apikeys:manage (owner, admin and developer have it).
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 });An access token is valid for 15 minutes. Get one by signing in as described in User tokens, use it for the task, and don’t store it.
| Method | HTTP | Returns |
|---|---|---|
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 |
Every key with its prefix, name, mode, scopes, IP allowlist, lastUsedAt, expiresAt and revokedAt. The secret is never returned.
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”Creates a key. Give it only the scopes it needs, and an expiry and IP allowlist where you can.
| Parameter | Type | Notes |
|---|---|---|
name |
string |
Shown in the portal and the audit log. |
scopes |
Permission[] |
For example ['messages:send', 'messages:read']. |
mode |
'live' | 'test' |
A test key sends through the sandbox; nothing reaches a real phone. |
expiresAt |
Date | string |
Optional. |
ipAllowlist |
string[] |
Optional IPs or CIDR ranges allowed to use the key. |
The result has apiKey (the stored key) and secret (the full sf_live_… or sf_test_… value), returned only this once.
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”Issues a new secret for the same key. The old secret keeps working until previousSecretExpiresAt, 24 hours later, so you can deploy the new one without downtime. rotate is not retried automatically.
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”Revokes a key at once. Requests that use it fail with 401 from then on.
import { SMSFabric } from '@smsfabric/sdk';
const admin = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
await admin.apiKeys.revoke('key_…');Creating, rotating and revoking keys is recorded in the audit log.