eSMS AfricaeSMS Africa
Authentication

API Keys

Create and manage API keys for the eSMS Mail REST API.

API keys authenticate requests to the eSMS Mail API. They are the recommended way to integrate eSMS Mail into your application.

Create an API key

  1. Go to send.esmsafrica.io → Settings → API Keys
  2. Click Create API Key
  3. Enter a name and select permissions
  4. Copy the key - it's only shown once

Via API

curl -X POST https://send.esmsafrica.io/v1/api-keys/ \
  -H "Authorization: Bearer esms_k_your_existing_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production key", "scope": "sending"}'

scope is a preset: full (everything), sending (send + read) or read (read-only). Alternatively pass an explicit permissions list such as ["send", "read"]; if you pass neither, the key gets ["send"] only. Add "environment": "test" for a sandbox key. See API Keys, Scopes & Environments.

Using API keys

Include the key in the Authorization header:

Authorization: Bearer esms_k_your_api_key

Key format

Live API keys start with esms_k_ and test (sandbox) keys with esms_test_, followed by a random secret. Example:

esms_k_abc123def456...

The first 8 characters after the esms_k_ / esms_test_ part are the key's key_prefix, shown in the dashboard for identification. The full key is only shown at creation time.

Revoking keys

Delete an API key to immediately revoke access:

curl -X DELETE https://send.esmsafrica.io/v1/api-keys/{key_id} \
  -H "Authorization: Bearer esms_k_your_api_key"

Best practices

  • Create separate keys for each environment (development, staging, production)
  • Use descriptive names so you know which key is which
  • Rotate keys periodically
  • Never commit API keys to version control
  • Use environment variables to store keys

On this page