Skip to content

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.

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
GET/v1/api-keysapikeys:manageuser token only

Returns every key in one page (nextCursor: null).

Terminal window
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:manageuser token only

Returns 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.
Terminal window
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.
POST/v1/api-keys/:id/rotateapikeys:manageuser token only

Issues 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.

Terminal window
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.)

DELETE/v1/api-keys/:idapikeys:manageuser token only

Requests with the key fail with 401 invalid_api_key immediately. Returns 204. Audited as apikey.revoked.

Terminal window
curl -X DELETE https://api.smsfabric.com/v1/api-keys/key_k5n8q1t4w7z0c3f6i9l2o5r8 \
-H "Authorization: Bearer $SMSFABRIC_USER_TOKEN"