eSMS AfricaeSMS Africa
eSMS Links

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>

Create keys in the dashboard under API Keys, or via POST /v1/keys. A key is shown once at creation - store it securely.

PrefixEnvironmentUse
esms_l_…LiveReal links, counts against your plan
esms_l_test_…TestA 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:

ScopeGrants
links:readRead-only: list and fetch links, QR codes, campaigns, domains, keys, analytics and account
links:writeCreate / 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

StatusMeaning
401Missing credentials, or an invalid/expired token or API key
403Valid credentials but missing the required scope, or the feature isn't on your plan
402A paid plan is required, or you've hit a monthly limit

On this page