Authentication
Secure your API requests with X-Api-Key or Bearer tokens, enforce granular scopes, and protect operations with idempotency.
All requests to the SMS Pro Developer Platform must be authenticated over HTTPS. Unauthenticated calls or requests with invalid keys will be rejected with an HTTP 401 Unauthorized or 403 Forbidden response.
Authentication Schemes
SMS Pro supports two standard methods for supplying your API credentials:
1. X-Api-Key Header (Recommended)
Pass your secret key in the custom X-Api-Key header:
POST /api/v1/public/sms/send HTTP/1.1
Host: api.smspro.com
X-Api-Key: sk_live_948f293048a1b2c3d4e5f60718a2b3c4
Content-Type: application/json2. Authorization: Bearer Header
Alternatively, use the RFC 6750 standard Bearer authorization scheme:
POST /api/v1/public/sms/send HTTP/1.1
Host: api.smspro.com
Authorization: Bearer sk_live_948f293048a1b2c3d4e5f60718a2b3c4
Content-Type: application/jsonAnatomy of an API Key
SMS Pro uses distinct, human-readable key prefixes to prevent accidental environment mismatches:
| Prefix | Behavior |
|---|---|
sk_test_ | Simulated delivery on https://api.smspro.com. No wallet charge. |
sk_live_ | Carrier delivery on the same API. Uses wallet credit. |
Same host
Test keys and live keys are both sent to https://api.smspro.com. The key prefix selects simulated delivery or carrier delivery.
Essential Request Headers
When constructing API calls, include the following headers:
| Header | Required? | Format / Value | Description |
|---|---|---|---|
X-Api-Key | Required* | sk_live_... or sk_test_... | Secret API key (*or use Authorization: Bearer). |
Content-Type | Required for POST/PUT | application/json | All request bodies must be JSON encoded. |
Idempotency-Key | Recommended for POST | UUID v4 (e.g. 9b1deb4d-...) | Unique request ID with a 24-hour cache TTL preventing duplicate dispatches on network retries. |
Understanding Idempotency Keys
Network blips and client timeouts can occur during mobile or server-to-server operations. If your application sends a payment receipt SMS and times out after 5 seconds, retrying the call blindly could result in the customer receiving duplicate text messages and your balance being deducted twice.
To prevent this, supply a unique Idempotency-Key on every mutating request:
const idempotencyKey = crypto.randomUUID();
const res = await fetch('https://api.smspro.com/api/v1/public/sms/send', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': process.env.SMSPRO_API_KEY!,
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify({
to: '+233241234567',
senderId: 'SMSPRO',
message: 'Your order #89201 has been dispatched.',
}),
});- If SMS Pro receives a request with an
Idempotency-Keythat was already processed within the past 24 hours, it immediately returns the cached initial response without re-queueing the SMS or billing your wallet again. - Idempotency keys are cached per-organization, so keys from different accounts will never collide.
Scope Verification & Principle of Least Privilege
Every API key has a specific set of granted permissions. If your key attempts to access an endpoint outside its configured scopes, the gateway returns HTTP 403 Forbidden:
{
"type": "https://docs.smspro.com/errors/forbidden-scope",
"title": "Forbidden Scope",
"status": 403,
"detail": "API key lacks the required 'mfa:write' scope to access this resource.",
"code": "AUTH_FORBIDDEN_SCOPE",
"requestId": "req-9b1deb4d",
"timestamp": "2026-11-18T08:45:00Z"
}To resolve this error, visit Developer > API Keys in the console and either edit the key's assigned scopes or generate a dedicated key with the required permissions.
Zero-Downtime Key Rotation
When cycling secrets or replacing a potentially compromised key, execute a zero-downtime rotation:
Generate a New Key
In the SMS Pro Console, generate a new scoped key with identical permissions and environments.
Update Application Secrets
Deploy the new key (SMSPRO_API_KEY) to your production staging and worker fleets.
Verify Traffic in API Logs
Navigate to Developer > API Logs and verify that requests are arriving successfully with the new key prefix.
Revoke the Old Key
Click Revoke on the legacy key in the console to permanently disable it.
Common Authentication Errors
| Status | Error Code | Root Cause & Resolution |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, unknown, or the caller address is not on the IP whitelist. |
403 | FORBIDDEN_SCOPE | The key does not include the scope for this endpoint. |
422 | API_KEY_ALLOCATION_EXCEEDED | The key has used its SMS allocation. |
Next Step
Learn how test keys and live keys share one API in Environments.