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.
API keys
Section titled “API keys”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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA 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.
export SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
curl https://api.smsfabric.com/v1/messages?limit=5 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"import { SMSFabric } from '@smsfabric/sdk';
// Reads SMSFABRIC_API_KEY when apiKey is omitted.const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sf.messages.list({ limit: 5 });console.log(page.data.length, 'messages');import osimport requests
session = requests.Session()session.headers.update({"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]})
res = session.get("https://api.smsfabric.com/v1/messages", params={"limit": 5}, timeout=30)res.raise_for_status()print(len(res.json()["data"]), "messages")<?php$ch = curl_init('https://api.smsfabric.com/v1/messages?limit=5');curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY')], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,]);$page = json_decode(curl_exec($ch), true);echo count($page['data']) . " messages\n";Scopes
Section titled “Scopes”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.
Restrict a key
Section titled “Restrict a key”When you create a key you can also set:
- Expiry (
expiresAt). After it, requests fail with401 api_key_expired. - IP allowlist (
ipAllowlist): up to 50 IPs or CIDR ranges. A request from any other address fails with403 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.
User tokens
Section titled “User tokens”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.
Authentication errors
Section titled “Authentication errors”| 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.