Skip to Content

Authentication

Secure your API requests with X-Api-Key or Bearer tokens, enforce granular scopes, and protect operations with idempotency.

View Markdown (.md)

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:

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/json

2. 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/json

Anatomy of an API Key

SMS Pro uses distinct, human-readable key prefixes to prevent accidental environment mismatches:

PrefixBehavior
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:

HeaderRequired?Format / ValueDescription
X-Api-KeyRequired*sk_live_... or sk_test_...Secret API key (*or use Authorization: Bearer).
Content-TypeRequired for POST/PUTapplication/jsonAll request bodies must be JSON encoded.
Idempotency-KeyRecommended for POSTUUID 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-Key that 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

StatusError CodeRoot Cause & Resolution
401UNAUTHORIZEDThe key is missing, unknown, or the caller address is not on the IP whitelist.
403FORBIDDEN_SCOPEThe key does not include the scope for this endpoint.
422API_KEY_ALLOCATION_EXCEEDEDThe key has used its SMS allocation.

Next Step

Learn how test keys and live keys share one API in Environments.

On this page