Authentication

The API has two independent auth schemes, used by two different surfaces. Use whichever matches what you're building.

X-API-Key (Public API)

For custom integrations, issue an API key from inside your account: Settings → API Keys (apikeys.manage permission). The full key value is shown exactly once, at creation - store it securely, since it can't be retrieved again.

Send it on every request as a header:

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxx

Each key is scoped to one or more of:

• sms.send - send messages
• sms.read - read message status and account balance

A key also carries its own per-minute rate limit (60/min by default) - see Rate limits.

Bearer JWT (Platform API)

The Platform API - the same endpoints the SimpliSend dashboard itself calls - is authenticated with a short-lived access token, obtained by logging in:

curl -X POST https://app.simplisend.co.za/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "your-password" }'

The response includes an access token and a refresh token:

{
  "user": { "id": "...", "email": "you@example.com", "fullName": "..." },
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi..."
}

Send the access token as a Bearer token on subsequent requests:

Authorization: Bearer eyJhbGciOi...

Access tokens are short-lived. When one expires, exchange your refresh token for a new one at POST /auth/refresh rather than logging in again. See the Auth reference for the full set of auth endpoints.

Which one should I use?

If you're building a server-side integration that only needs to send messages and check on them, use an API key - it's simpler, doesn't expire, and can't do anything beyond its granted scopes. Use a JWT only if you specifically need account-management capabilities (contacts, campaigns, billing, team management) that the Public API doesn't expose.