Skip to content

Authentication ​

Every request (except the /s/:code redirect) must carry an Authorization header. Three schemes are accepted.

SchemeHeaderStatus
API keyAuthorization: Bearer smsk_...Recommended
BasicAuthorization: Basic base64(username:password)Supported (legacy compatible)
Legacy tokenAuthorization: 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.

An API key is smsk_ + 8 characters + _ + 32 characters (A–Z, a–z, 0–9), for example

text
smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01
bash
curl 'https://public-api.smsup-plus.com/sms/senderlist' \
  -H 'Authorization: Bearer smsk_Ab12Cd34_0123456789abcdefghijABCDEFGHIJ01'
js
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())
PropertyDetails
Where to createCustomer portal
StorageOnly a hash of the key is stored — the full key is shown once at creation; if lost, create a new one
CountUp to 10 active keys per user
LifetimeNever expires, or 30 / 90 / 180 / 365 days
IP restrictionOptional list of allowed IPs or CIDRs per key — empty means any IP
IdentityA key acts as the user who created it; the user and account must still be active
RevocationRevoke in the portal; takes effect within about 10 seconds

Basic ​

Send the customer-portal user's username:password, Base64-encoded.

bash
curl 'https://public-api.smsup-plus.com/sms/senderlist' \
  -u 'myuser:mypassword'
# same as -H 'Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ='
js
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>"}.

HTTPerrorCause
401missing authorization headerNo Authorization header
401invalid authorization formatHeader is not <scheme> <value>
401unsupported authorization schemeScheme is neither Bearer nor Basic
401invalid api keyUnknown API key
401api key revokedAPI key was revoked
401api key expiredAPI key has expired
403ip not allowedSource IP is not in the key's allowed list
401session revokedThe credential owner's user or account is suspended
401invalid basic auth encodingBasic value is not valid Base64
401invalid credentials formatDecoded value has no :
401invalid credentialsWrong username or password
401user account is inactiveUser is disabled
401account is inactiveAccount is disabled
401invalid tokenLegacy token is invalid or expired
401web session token not accepted, use an API keyToken from a portal website sign-in
401api token revokedLegacy token was revoked
401legacy api token disabled, use an API keyLegacy tokens are switched off
500internal errorTemporary failure, retry

Rate limits ​

Applied to the /sms/* and /OTP/* endpoints, counted in 1-second windows.

ScopeDefault
Per source IP (counted before credentials are checked)100 requests/second
Per account50 requests/second (can be adjusted per account — contact support)
Per API keyNo separate limit (counts toward the account limit)

Exceeding a limit returns HTTP 429 with the header Retry-After: 1.

json
{
  "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.

TopicDetails
HeaderIdempotency-Key: <value> (optional — without it requests behave normally)
FormatA–Z a–z 0–9 _ -, 1–128 characters, e.g. a UUID
ScopePer account — the same key from different accounts does not collide
Result kept24 hours, successful results (HTTP 2xx) only
ReplaySame HTTP status and body returned, plus header Idempotent-Replayed: true
Failed resultKey is not kept — you may retry with the same key immediately
bash
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"}]}'
HTTPResponseCause
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.