Authentication

API keys

Keys are created in the portal under Developer, API tab. Each key is a 64-character string tied to your account; you can hold several at once (one per system is a good habit), give each a name and an IP allow-list, and regenerate or delete any of them. The portal shows when a key was last used.

A key grants everything the account can do over the API: sending on every channel and reading balances. Treat it like a password: keep it on the server, never in a browser or a mobile app, and regenerate it if it leaks.

Sending the key

Put the key in a request header. X-API-Key is checked first and is the form every example in these docs uses.

# Recommended
X-API-Key: YOUR_API_KEY

# Also accepted
Authorization: Bearer YOUR_API_KEY

# Legacy: HTTP Basic with the key as the username and an empty password
Authorization: Basic base64("YOUR_API_KEY:")

With Basic auth the gateway accepts the key on either side of the colon, so base64(":YOUR_API_KEY") works too. Leading and trailing whitespace around the key is trimmed.

What is checked

Before a request reaches an endpoint, the gateway checks, in this order:

1. A key is present and matches a credential.
2. The credential is enabled.
3. The account it belongs to exists and is active.
4. The credential has not passed its expiry date, if one was set.
5. The caller's IP address is on the credential's allow-list, if one was set.
6. The credential is under its requests-per-minute limit.

The first check that fails ends the request with HTTP 401 (or 429 for the rate limit) and a JSON body naming the reason. A request that passes all six is logged against that credential, so the portal can show which key sent what.

{
  "message": "IP_NOT_ALLOWED",
  "success": false,
  "api_reference": "1764184470578998353"
}

Rate limits

Each credential has a requests-per-minute limit, counted per calendar minute. The default is 60. Going over it answers 429 with RATE_LIMIT_EXCEEDED until the next minute starts; requests refused this way send nothing and cost nothing. The limit is set per credential by Unicom360; ask support if a system needs more. Note that it counts requests, not recipients: one request to 2,000 numbers is one request.

IP allow-list

When you add addresses to a credential's allow-list, only requests from those addresses are accepted; the rest get IP_NOT_ALLOWED. Add the public addresses your servers send from. An empty list allows any address, as does the literal *. Restricting a key to the addresses that actually use it is the single most effective protection against a leaked key.

Expiry and rotation

A credential can carry an expiry date, after which it answers CREDENTIAL_EXPIRED. To rotate a key without downtime, create a second credential, move your systems to it, then delete the old one. Regenerating a key in place replaces it immediately: anything still sending the old value fails from that moment.

Authentication errors

HTTP 401 (429 for the rate limit) with {"message": "<code>", "success": false, "api_reference": "..."}. JSON on every endpoint, including the XML one.

Every other error the gateway returns is listed on the Errors page.