Skip to content

Authentication

Every request to https://api.smsfabric.com is denied unless it carries a credential. Your server code uses an API key. The portal uses a short-lived user token. This page covers both, and when each one is accepted.

An API key belongs to one organization and carries a fixed set of scopes. Send it in the X-Api-Key header:

X-Api-Key: sf_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A key has three parts, separated by underscores:

Part Example Meaning
Mode sf_live_ or sf_test_ live sends real SMS through your phones. test runs in the sandbox and never touches a phone.
Prefix ab12cd34ef56 12 lowercase letters and digits. It identifies the key and is shown in the portal and in GET /v1/api-keys.
Secret 32 letters and digits Shown once, when you create or rotate the key. SMSFabric stores only a peppered SHA-256 hash of it.

Create keys in the portal under Developers → API keys (see API keys in the portal) or with POST /v1/api-keys while signed in. Store the key in an environment variable or a secret manager, never in source control.

Terminal window
export SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
curl https://api.smsfabric.com/v1/messages?limit=5 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"

Scopes are permission strings. A request succeeds only when the key holds every permission the endpoint needs; otherwise the API answers 403 with code: "missing_permission". Each reference entry shows its scope next to the path.

Scope Lets the key
messages:send Send messages (POST /v1/messages). Starting a campaign also needs it.
messages:read Read messages and stats.
logs:export Download CSV exports.
devices:read / devices:manage Read devices, SIMs and pools / pair, rename, unpair and configure them.
contacts:read / contacts:manage Read / change contacts, groups and imports.
campaigns:read / campaigns:manage Read / change templates and campaigns.
blacklist:manage Read and change the blacklist.
verify:send / verify:check Send one-time codes / check them and read verifications.
webhooks:manage Create and manage webhook endpoints.
settings:manage Change sending preferences.
audit:read Read the audit log.

Give each key only what its caller needs. A backend that sends OTPs needs verify:send and verify:check, nothing else.

You can only grant scopes your own role holds. Asking for more returns 403 with code: "scope_escalation". The roles and their permissions are listed in Team in the portal.

When you create a key you can also set:

  • Expiry (expiresAt). After it, requests fail with 401 api_key_expired.
  • IP allowlist (ipAllowlist): up to 50 IPs or CIDR ranges. A request from any other address fails with 403 ip_not_allowed.

Rotate a key with POST /v1/api-keys/:id/rotate. You get a new secret, and the old one keeps working for 24 hours so you can deploy without downtime. Revoke a key with DELETE /v1/api-keys/:id; requests with it fail immediately.

The portal signs in with POST /v1/auth/login and sends a 15-minute access token as Authorization: Bearer <token>. You rarely need this from code. A few endpoints accept only a signed-in user, so that a leaked API key cannot widen its own access:

Endpoint Why
GET /v1/api-keys, POST /v1/api-keys, POST /v1/api-keys/:id/rotate, DELETE /v1/api-keys/:id A key must not mint or revoke keys.
PATCH /v1/org, GET /v1/org/members, POST /v1/org/invitations and the other team endpoints Team and organization changes.
PUT /v1/verify/settings Verify geo permissions.
GET /v1/auth/sessions, POST /v1/auth/2fa/setup and the other sign-in endpoints Sessions and 2FA belong to a person.

An API key on one of these returns 403 with code: "api_key_not_allowed". The reference marks them user token only.

Status code What happened What to do
401 unauthorized No credential was sent. Add the X-Api-Key header.
401 invalid_api_key The key is malformed, unknown or revoked. Check for whitespace or a truncated value; create a new key if it was revoked.
401 api_key_expired The key’s expiresAt has passed. Create or rotate a key.
403 ip_not_allowed The caller’s IP is not on the key’s allowlist. Add the address, or call from an allowed host.
403 missing_permission The key lacks a scope the endpoint needs. Create a key with that scope.
403 api_key_not_allowed The endpoint is for signed-in users only. Do it in the portal.
403 tenant_suspended The organization is suspended. Contact support.

See Errors for the full list.