Authentication

Every request carries one of your API keys as a bearer token.

GET /v1/messages HTTP/1.1
Host: api.siellabs.com
Authorization: Bearer smsgw_…

Create keys on the API keys page. A key is shown once, when it's created; we keep only a hash, so a lost key can't be recovered: create a new one and revoke the old.

Keep keys on your server#

A key can send messages and spend your balance. Never put one in a mobile app, a web page or a public repository. Use one key per system (production, staging, a partner integration) so that you can revoke one without touching the others.

Keys and products#

If your account has more than one product (for example a marketing and a transactional one, at different prices and routes), each key sends under the product it was created for. Pick the product when you create the key.

Limiting a key#

On the API keys page, a key can be limited, when it's created or later, so a leaked one can do little:

• Where it can be used from: your servers' addresses, or ranges like 203.0.113.0/24. Calls from anywhere else are refused.
• What it can do: full access, or only the permissions you give it, below.
• Until when: an expiry date, after which it stops working.

Changes apply within seconds; the key itself stays the same. Refused calls are listed under Fraud protection, Activity, with the key's name and where they came from: a leaked key being tried shows there.

When a key is refused#

A missing, unknown or revoked key gets HTTP 401 with error code unauthorized; a key past its expiry date, 401 key_expired. A key used from an address it doesn't allow gets 403 ip_not_allowed, and one used for something it may not do, 403 permission_denied. A suspended account gets 403. See Errors.

{
  "error": {
    "code": "unauthorized",
    "message": "unknown or revoked API key"
  }
}