API keys
An API key lets your server call the SMSFabric API. Each key belongs to one organization, is either a test key or a live key, and carries only the scopes you give it. How keys are sent and checked is in Authentication.
Create a key
Section titled “Create a key”-
Open API keys in the sidebar under Developers.
Open API keys. -
Click Create API key. If your plan’s limit on API keys is reached, the button is dimmed and says why; see Plan and usage.
Click Create API key. -
Give the key a Name after what will use it, such as “Order notifications”. Under Mode, choose Test · sandbox or Live · real SMS.
Name the key and choose its mode. -
Tick the Scopes the caller needs, and nothing more. A backend that only sends needs
messages:send; addmessages:readif it also checks statuses.Pick the scopes. -
Choose when the key Expires: in 30 days, 90 days, 1 year, or never (not recommended). Under IP allowlist, optionally enter the addresses your servers call from, separated by commas, as single IPs or CIDR ranges such as
198.51.100.0/24. Leave it empty to allow any IP. Then click Create key.Set the expiry and, optionally, an IP allowlist. -
Copy the secret now and store it in your secret manager or environment, then click I’ve stored it. The portal never shows it again; if you lose it, rotate the key.
Copy the secret and store it.
A key looks like sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx: the mode, a 12-character prefix that identifies it, and the secret. Send it in the X-Api-Key header.
Read the key list
Section titled “Read the key list”| Column | Shows |
|---|---|
| Name | The name, and the key’s prefix (sf_live_k2v8x0_••••) so you can match it to your config |
| Mode | Live or test |
| Scopes | What the key can do. The first three, then +N for the rest. |
| Last used | When the key last made a request, or Never |
| Expires | When it stops working, or No expiry |
A key nobody has used for months is a candidate to revoke.
Rotate a key
Section titled “Rotate a key”Rotate a key when the secret may have leaked, when someone who knew it leaves, or on a regular schedule.
-
Click ⋮ at the end of the key’s row.
Open the key's actions. -
Click Rotate secret…, then Rotate secret to confirm.
Confirm the rotation. -
Copy the new secret and deploy it. The old secret keeps working for 24 hours, so your servers can switch over without downtime; after that it stops.
Copy the new secret and deploy it within 24 hours.
Revoke a key
Section titled “Revoke a key”Revoke a key you no longer use, or one that leaked and you can’t wait 24 hours on.
-
Open the key’s ⋮ menu and click Revoke…. Type
revoketo confirm, then click Revoke key. Requests with the key fail at once with401. This can’t be undone.Type revoke and click Revoke key.
Creating, rotating and revoking keys are written to the audit log.
Who can manage keys
Section titled “Who can manage keys”Managing keys needs apikeys:manage, which the Owner, Admin and Developer roles have. You can only give a key scopes your own role holds. Keys are managed only by signed-in people: an API key can’t create, rotate or revoke keys. See Team for the roles and Authentication for what each scope allows.