API Keys

Create a key

POST /api/api-keys

{
  "name": "Production server",
  "environment": "live",
  "scopes": "send,query"
}

Field	Type	Required	Description
`name`	string	Yes	Human-readable label for this key
`environment`	string	Yes	`live` or `test`
`scopes`	string	Yes	Comma-separated list of scopes

Response:

{
  "id": 12,
  "key": "esms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "name": "Production server",
  "prefix": "esms_live_****o5p6",
  "environment": "live",
  "scopes": ["send", "query"],
  "created_at": "2026-05-02T10:00:00Z"
}

The full key is shown once only in the response. Copy it immediately and store it securely. You cannot retrieve it again.

Scopes

Scope	Allowed operations
`send`	`POST /api/messages/send`, `POST /api/messages/send-bulk`, `POST /api/messages/bulk-precheck`
`query`	`GET /api/messages`, `GET /api/messages/{id}`, `GET /api/balance`, `GET /api/balance/transactions`, `GET /api/routes`
`webhooks`	`GET /api/webhooks`, `PUT /api/webhooks`, `POST /api/webhooks/rotate-secret`

Request only the scopes your integration needs. A key with only query scope cannot send messages.

List keys

GET /api/api-keys

[
  {
    "id": 12,
    "name": "Production server",
    "prefix": "esms_live_****o5p6",
    "environment": "live",
    "scopes": ["send", "query"],
    "is_active": true,
    "last_used_at": "2026-05-02T11:30:00Z",
    "created_at": "2026-05-02T10:00:00Z"
  }
]

The prefix shows the first 8 chars plus the last 4 - enough to identify the key without exposing it.

Revoke a key

DELETE /api/api-keys/{key_id}

Revocation is immediate. Any in-flight requests using the key will fail.

Best practices

One key per service - create separate keys for your API server, scripts, and integrations. This lets you revoke one without disrupting others.
Use environment variables - never hardcode keys in source code.
Rotate regularly - create a new key, update your service, then revoke the old one.
Use test keys for development - avoid real charges and message delivery during testing.

Environment variables example

# .env
ESMS_API_KEY=esms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

import os
import httpx

client = httpx.Client(
    base_url="https://sms.esmsafrica.io/api",
    headers={"Authorization": f"Bearer {os.environ['ESMS_API_KEY']}"},
)