Authentication

The SMS API uses an API key and API secret to authenticate requests.

Your credentials are created when you create an SMS API application.

API credentials

Each SMS API application has:

• API Key — identifies your API application.
• API Secret — authenticates your request.

Keep your API secret private. Do not expose it in frontend JavaScript, mobile applications, public repositories or other client-side code.

Request headers

Include the following headers with every API request:

X-API-KEY: your-api-key
X-API-SECRET: your-api-secret
Idempotency-Key: unique-request-key
Content-Type: application/json

X-API-KEY

Your API application's public API key.

X-API-KEY: your-api-key

X-API-SECRET

Your API application's secret.

X-API-SECRET: your-api-secret

The secret should only be stored and used on your server.

Idempotency-Key

A unique key for the request.

Idempotency-Key: unique-request-key

The idempotency key helps prevent the same request from being processed more than once.

See Idempotency for more information.

Content-Type

Requests containing JSON data must use:

Content-Type: application/json

Example request

POST {{BASE_URL}}/api/v1/sms
X-API-KEY: your-api-key
X-API-SECRET: your-api-secret
Idempotency-Key: 8c7f2a91-1d5e-4c3b-a7e2-91c4f8b62310
Content-Type: application/json

{
  "msisdns": [
    "254701234567"
  ],
  "message": "Hello from Jane Doe",
  "sender_name": "TEST_SENDER"
}

Invalid credentials

If the API key or API secret is invalid, the request is rejected.

Example:

{
  "success": false,
  "message": "Invalid API credentials.",
  "error": "INVALID_REQUEST",
  "data": null
}

The API returns HTTP 422 for invalid API credentials.

Security