Authentication
Every request (except the /s/:code redirect) must carry an Authorization header. Three schemes are accepted.
| Scheme | Header | Status |
|---|---|---|
| API key | Authorization: Bearer smsk_... | Recommended |
| Basic | Authorization: Basic base64(username:password) | Supported (legacy compatible) |
| Legacy token | Authorization: Bearer <JWT> | Supported for older integrations — migrate to API keys |
WARNING
Bearer and Basic must be spelled exactly like this (capital first letter), followed by a single space.
API key (recommended)
An API key is smsk_ + 8 characters + _ + 32 characters (A–Z, a–z, 0–9), for example
smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01curl 'https://public-api.smsup-plus.com/sms/senderlist' \
-H 'Authorization: Bearer smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01'const res = await fetch('https://public-api.smsup-plus.com/sms/senderlist', {
headers: { Authorization: `Bearer ${process.env.SMSUP_API_KEY}` },
})
console.log(await res.json())| Property | Details |
|---|---|
| Where to create | Customer portal |
| Storage | Only a hash of the key is stored — the full key is shown once at creation; if lost, create a new one |
| Count | Up to 10 active keys per user |
| Lifetime | Never expires, or 30 / 90 / 180 / 365 days |
| IP restriction | Optional list of allowed IPs or CIDRs per key — empty means any IP |
| Identity | A key acts as the user who created it; the user and account must still be active |
| Revocation | Revoke in the portal; takes effect within about 10 seconds |
Basic
Send the customer-portal user's username:password, Base64-encoded.
curl 'https://public-api.smsup-plus.com/sms/senderlist' \
-u 'myuser:mypassword'
# same as -H 'Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ='const auth = Buffer.from('myuser:mypassword').toString('base64')
const res = await fetch('https://public-api.smsup-plus.com/sms/senderlist', {
headers: { Authorization: `Basic ${auth}` },
})
console.log(await res.json())The user must be active and the user's account must be active.
TIP
Prefer API keys over Basic — a key can be revoked individually, restricted by IP, and keeps your password out of your systems.
Legacy token (JWT)
JWT tokens issued to older integrations still work as Authorization: Bearer <JWT>, with these conditions:
- Tokens from signing in to the portal website are not accepted (
web session token not accepted, use an API key) - The user and account must still be active and the token must not be revoked
Use API keys for new integrations.
Authentication errors
Every error at this stage is {"error": "<message>"}.
| HTTP | error | Cause |
|---|---|---|
| 401 | missing authorization header | No Authorization header |
| 401 | invalid authorization format | Header is not <scheme> <value> |
| 401 | unsupported authorization scheme | Scheme is neither Bearer nor Basic |
| 401 | invalid api key | Unknown API key |
| 401 | api key revoked | API key was revoked |
| 401 | api key expired | API key has expired |
| 403 | ip not allowed | Source IP is not in the key's allowed list |
| 401 | session revoked | The credential owner's user or account is suspended |
| 401 | invalid basic auth encoding | Basic value is not valid Base64 |
| 401 | invalid credentials format | Decoded value has no : |
| 401 | invalid credentials | Wrong username or password |
| 401 | user account is inactive | User is disabled |
| 401 | account is inactive | Account is disabled |
| 401 | invalid token | Legacy token is invalid or expired |
| 401 | web session token not accepted, use an API key | Token from a portal website sign-in |
| 401 | api token revoked | Legacy token was revoked |
| 401 | legacy api token disabled, use an API key | Legacy tokens are switched off |
| 500 | internal error | Temporary failure, retry |
Rate limits
Applied to the /sms/* and /OTP/* endpoints, counted in 1-second windows.
| Scope | Default |
|---|---|
| Per source IP (counted before credentials are checked) | 100 requests/second |
| Per account | 50 requests/second (can be adjusted per account — contact support) |
| Per API key | No separate limit (counts toward the account limit) |
Exceeding a limit returns HTTP 429 with the header Retry-After: 1.
{
"error": {
"statusCode": "429",
"description": "rate limit exceeded: max 50 requests per second per account",
"message": "TOO_MANY_REQUESTS"
}
}description ends with per IP, per account or per API key depending on the limit hit. Wait at least Retry-After seconds, then retry.
Idempotency-Key (duplicate protection)
Applies to POST /sms/send and POST /OTP/requestotp only — a retry with the same key is not sent again and not charged again.
| Topic | Details |
|---|---|
| Header | Idempotency-Key: <value> (optional — without it requests behave normally) |
| Format | A–Z a–z 0–9 _ -, 1–128 characters, e.g. a UUID |
| Scope | Per account — the same key from different accounts does not collide |
| Result kept | 24 hours, successful results (HTTP 2xx) only |
| Replay | Same HTTP status and body returned, plus header Idempotent-Replayed: true |
| Failed result | Key is not kept — you may retry with the same key immediately |
curl -X POST 'https://public-api.smsup-plus.com/sms/send' \
-H 'Authorization: Bearer <API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 7d9f2c1e-4b8a-4e0f-9a3b-1c2d3e4f5a6b' \
-d '{"messages":[{"from":"MYBRAND","destinations":[{"to":"0812345678"}],"text":"hello"}]}'| HTTP | Response | Cause |
|---|---|---|
| 400 | {"error":"invalid Idempotency-Key"} | Header value has the wrong format |
| 409 | {"error":"request with this Idempotency-Key is in progress"} | An earlier request with the same key is still running — wait and retry |
WARNING
The body is not compared — reusing a key with different data within 24 hours returns the first request's result without sending anything new. Use a new key for every new send.
API call logging
Every request to an authenticated endpoint is recorded in the API call history (including requests whose credentials fail). The API key value itself is never recorded.
