Skip to main content
Everything under /secure/ takes HTTP Basic authentication, with your login as the username. /ping takes none.
Or the header directly, if your client does not build it for you:

​
Credentials go in the header, nowhere else

username and password as body fields are not ignored — they come back as 400 Unknown argument. That refusal is usually the first sign of a payload copied from a different gateway.

​
An SMPP login cannot use this API

This catches people out because the refusal does not say so. A 403 Authentication failure covers all three of: unknown login, wrong password, and a login of the wrong type.
If a login works over SMPP and returns 403 here, check its type before you check its password. Credentials are typed HTTP or SMPP and the two are not interchangeable — one login cannot do both.

​
The two 401s

They mean different things, and the distinction is worth branching on: Executed against a live gateway:
401 means you did not identify yourself. 403 means you did, and it was not accepted. Worth wiring into your alerting separately: a sudden 401 is usually a deployment that lost an environment variable, a sudden 403 a rotated password or a moved IP.

​
IP allow lists

If your login has one, a request from anywhere else is 403 Authorization failure — a different message from the credential failure above, so the two are distinguishable in a log. Your gateway operator sets this. It is worth asking whether one is configured before you move your integration to new infrastructure.

​
Authentication runs before everything

Confirmed live: a POST with no credentials and an unparseable body returns the authentication error, not the parse error.
Fix credentials before debugging a payload. A 401 or 403 tells you nothing about whether the rest of your request is correct, because nothing downstream of authentication has run.

​
Keeping the password safe

  • Read it from the environment or a secret store, never from source.
  • It is not rotated for you — if it leaks, ask your operator to change it.
  • An unknown path under /secure/ returns 401, not 404, so the API will not confirm which endpoints exist to an unauthenticated caller. Do not build discovery on top of status codes.

API errors

Every status, and which are worth retrying.

Quickstart

First message in four languages.