API keys
API keys authenticate your servers. These endpoints need a signed-in user with the apikeys:manage permission: an API key can’t create, rotate or revoke keys (403 api_key_not_allowed). Most people use Developers → API keys in the portal instead (walkthrough). The examples send a user access token as Authorization: Bearer.
The API key object
Section titled “The API key object”| Field | Type | Description |
|---|---|---|
id |
string | key_… |
name |
string | What uses the key, such as Production backend. |
prefix |
string | The public part, such as sf_live_ab12cd34ef56. Never the secret. |
mode |
string | live or test. |
scopes |
string[] | Permissions the key carries. |
ipAllowlist |
string[] | IPs or CIDR ranges allowed to use it. Empty means any. |
lastUsedAt |
string or null | |
expiresAt |
string or null | |
revokedAt |
string or null | |
createdAt |
string |
List keys
Section titled “List keys”/v1/api-keysapikeys:manageuser token onlyReturns every key in one page (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}Create a key
Section titled “Create a key”/v1/api-keysapikeys:manageuser token onlyReturns 201 with apiKey and secret, the full key. The secret is shown only this once. Supports Idempotency-Key. Audited as apikey.created.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
name |
string | Yes | 1 to 120 characters. | |
scopes |
string[] | Yes | Permissions to grant. | Only permissions your own role holds. |
mode |
string | Yes | live sends real SMS; test uses the sandbox. |
live or test. |
expiresAt |
string | No | When the key stops working. | ISO 8601, in the future. |
ipAllowlist |
string[] | No | Allowed IPs or CIDR ranges. | Up to 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"}| Error | When |
|---|---|
403 scope_escalation |
A scope your role doesn’t have. |
403 api_key_not_allowed |
Called with an API key. |
400 validation_failed |
Unknown scope, invalid CIDR, or expiresAt in the past. |
Rotate a key
Section titled “Rotate a key”/v1/api-keys/:id/rotateapikeys:manageuser token onlyIssues a new secret for the same key (same id, prefix and scopes). The old secret keeps working until previousSecretExpiresAt, 24 hours later, so you can deploy the new one without downtime. Returns 200. Audited as 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 is shortened here.)
Revoke a key
Section titled “Revoke a key”/v1/api-keys/:idapikeys:manageuser token onlyRequests with the key fail with 401 invalid_api_key immediately. Returns 204. Audited as apikey.revoked.
curl -X DELETE https://api.smsfabric.com/v1/api-keys/key_k5n8q1t4w7z0c3f6i9l2o5r8 \ -H "Authorization: Bearer $SMSFABRIC_USER_TOKEN"