Authentication
Authenticate to the eSMS Links API with a Bearer JWT session or an esms_l_ API key.
Every request to the eSMS Links API is authenticated with a Bearer token in the Authorization header. Two token types are accepted.
Authorization: Bearer <token>API keys (recommended for servers)
Create keys in the dashboard under API Keys, or via POST /v1/keys. A key is shown once at creation - store it securely.
| Prefix | Environment | Use |
|---|---|---|
esms_l_… | Live | Real links, counts against your plan |
esms_l_test_… | Test | A separately labelled key for development and CI |
curl https://links.esmsafrica.io/v1/links \
-H "Authorization: Bearer esms_l_your_key"Test keys are currently a label only: they are not a sandbox. Links, QR codes and other resources created with a test key are real, resolve publicly, and count against your plan's monthly limits.
Scopes
Keys are scoped. Assign the least privilege a key needs:
| Scope | Grants |
|---|---|
links:read | Read-only: list and fetch links, QR codes, campaigns, domains, keys, analytics and account |
links:write | Create / update / delete links, QR codes, campaigns, branded domains and API keys |
* | Full access (default when no scopes are given) |
Read (GET) endpoints accept any valid key, whatever its scopes. Every write endpoint requires links:write (or *), so a key created with only links:read is a read-only key. A request that lacks the required scope returns 403 Missing scope: ….
JWT sessions (dashboard)
The dashboard authenticates with your central eSMS Africa session (single sign-on). The same JWT works against the API as a Bearer token and always has full access. Sign in at links.esmsafrica.io - the session cookie is shared across *.esmsafrica.io.
One eSMS Africa account signs you into SMS, Mail, SMPP and Links. Your Links plan tier travels in the session, and API keys carry your current plan too (looked up from your account and refreshed every few minutes), so the API enforces the right limits automatically.
Errors
| Status | Meaning |
|---|---|
401 | Missing credentials, or an invalid/expired token or API key |
403 | Valid credentials but missing the required scope, or the feature isn't on your plan |
402 | A paid plan is required, or you've hit a monthly limit |