Start

Authentication

One API key per system, sent on every request. No tokens to refresh, nothing to expire in the middle of the night.

The header

Send your key as a bearer token. That is the whole of it.

shell

curl https://sendrixbackend.exebee.com/v1/templates \
  -H "Authorization: Bearer sk_live_your_key_here"

Keys are created in Developers in the console, by a workspace admin. The secret is shown once, when it is made. We store only a hash of it, so we genuinely cannot show it to you again, and neither can anyone who reaches our database.

Scopes

A key only does what you granted it. Give each system the least it needs: a job that reads delivery reports has no business holding a credential that can spend credits.

Scope	What it allows
`senders:read`	List the WhatsApp numbers on this workspace.
`templates:read`	List templates and the variables each one needs.
`messages:send`	Send messages. This one spends credits.
`messages:read`	Read back the status of a message it sent.
`webhooks:read`	Read the webhook endpoint configuration.

A request without the right scope is refused with insufficient_scope, and the error names both what was needed and what the key actually has.

Rate limits

Each key has its own budget, counted per minute. The default is 30 requests a minute and the most any key can have is 100. Change it per key on the keys page.

Every response tells you where you stand:

http

RateLimit-Limit: 30
RateLimit-Remaining: 24
RateLimit-Reset: 41

RateLimit-Reset is seconds until the window rolls over. Go past the limit and you get a 429 with Retry-After set to the same number. Wait that long rather than retrying immediately.

Restricting where a key works

A key can be limited to a list of IP addresses. Set it on the key and a request from anywhere else is refused with ip_not_allowed, which turns a leaked key into a useless one for anybody outside your network. Leave it empty and the key works from anywhere.

Checking a key

GET /v1/me tells you which workspace a key belongs to and what it may do. Useful in a health check, and the fastest way to confirm you deployed the key you meant to.

shell

curl https://sendrixbackend.exebee.com/v1/me \
  -H "Authorization: Bearer sk_live_your_key_here"

json

{
  "account_id": "8ecaf1c4-76a0-4464-848e-6dcb3bb69ed8",
  "key": {
    "id": "a841eb54-e4f9-413c-9f9b-c8c34d15a02f",
    "name": "Order service",
    "scopes": ["templates:read", "messages:send"]
  },
  "rate_limit_per_min": 30
}

When a key stops working

Four things can refuse a key, and each says which:

invalid_key, the key is not one of ours.
key_revoked, somebody revoked it in the console.
key_expired, it was created with an expiry that has passed.
workspace_suspended, the workspace itself is suspended.

Every request is logged either way. If your integration starts failing, Developers, then Activity in the console shows what was refused and why, grouped by error, without you having to reproduce it.

The header#

Scopes#

Rate limits#

Restricting where a key works#