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 | Sandbox - build and test without touching live data |
curl https://links.esmsafrica.io/v1/links \
-H "Authorization: Bearer esms_l_your_key"Scopes
Keys are scoped. Assign the least privilege a key needs:
| Scope | Grants |
|---|---|
links:read | Read links, QR codes, analytics, account |
links:write | Create / update / delete links, QR codes, domains |
* | Full access (default when no scopes are given) |
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, 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 |
402 | A paid plan is required, or you've hit a monthly limit |