Authentication

There are two credentials. Each reference page says which one it takes on its Authentication line.

API key

One key per company. It signs the messaging calls. Where the key goes depends on the call:

Calls	Where the key goes	Name
SMS, one-time codes, balance, sender names (`/api/SendSMS`, `/api/Verify`, `/api/CheckBalance` and the others without `/partners/` in the address), POST form	JSON body	`api_id`
The same calls, GET form	Query string	`api_id`
Viber and WhatsApp (`/api/partners/viber-…`, `/api/partners/whatsapp-…`, `/api/partners/senders`)	Request header	`apiId`
SMS records (`/api/partners/SmsDataRecords`)	JSON body for the list call, query string for the single record	`apiId`

Good practice:

Prefer the POST form of a call. With the GET form the key travels in the address, where proxies and logs can
keep it.

Call from your server only. Never put the key in a web page or a mobile app.

If a key may have leaked, replace it with Replace the API key. The old key stops working at
once.

Allowed IP addresses

You can limit the key to a list of IP addresses with Set the allowed IP addresses. When the
list is empty, the key works from any address. When it is set, a call from any other address is refused:

HTTP/1.1 401 Unauthorized

{"message": "Access denied: your IP is not in the allowed list. Configure your allowed IPs in the partner portal."}

A wrong key, and a key of an account that is not active, get this same answer. When you see it, check the key first.

We recommend setting the list for every production key.

Every call that is not a messaging call takes a login token in the header Authorization: Bearer <token>.

1. Sign in with Sign in (for programs):

{
  "data": [
    {
      "requiresTwoFactor": false,
      "token": {
        "token": "<login token>",
        "refreshToken": "<refresh token>",
        "tokenLifeTime": "00:15:00"
      }
    }
  ]
}

2. Call with the token:

3. Renew before tokenLifeTime ends, with Refresh the login token. Send the token you
hold and the refresh token; you get a new pair. A refresh token works once. If the refresh answers 401, sign in
again.

4. Sign out with Sign out when the program stops for good.

Things to know:

Use a dedicated account for an integration, without two-step sign-in. An account with two-step sign-in gets
requiresTwoFactor: true and no token from this call.

Sign-in is limited to 20 calls per 5 minutes per IP address. Sign in once and renew; do not sign in before
every call.

A call with a missing, wrong or expired token answers 401. See Errors for the body.

The same token works on every server address (see Addresses and formats).

Authentication

API key#

Allowed IP addresses#

Login token#

API key

Allowed IP addresses

Login token