Skip to content

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.

  1. Open API keys in the sidebar under Developers.

    Open API keys.
  2. 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.
  3. 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.
  4. Tick the Scopes the caller needs, and nothing more. A backend that only sends needs messages:send; add messages:read if it also checks statuses.

    Pick the scopes.
  5. 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.
  6. 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.

The list of keys.
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 when the secret may have leaked, when someone who knew it leaves, or on a regular schedule.

  1. Click ⋮ at the end of the key’s row.

    Open the key's actions.
  2. Click Rotate secret…, then Rotate secret to confirm.

    Confirm the rotation.
  3. 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 you no longer use, or one that leaked and you can’t wait 24 hours on.

  1. Open the key’s ⋮ menu and click Revoke…. Type revoke to confirm, then click Revoke key. Requests with the key fail at once with 401. This can’t be undone.

    Type revoke and click Revoke key.

Creating, rotating and revoking keys are written to the audit log.

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.