API keys & scopes

Every request authenticates with an API key sent in the X-API-Key header:

X-API-Key: <API_KEY>

Creating a key

Keys are created in the Client portal at client.routeon.io under API Accesses → API key generation:

  1. Enter a Name for the key.
  2. Optionally set a Webhook URL — the fallback destination for status events from traffic sent with this key (it can be overridden per request).
  3. Select the Scopes the key needs (see below).
  4. Click Create API key and store the value securely — treat it like a password.

Scopes

A key works only for the scopes selected on it. If a request needs a scope the key does not have, it fails with 401. REJECTD is an SMSC delivery status, not a scope error.

Scope Unlocks
omni-api Single transactional messages and OTP — POST /messages, POST /messages/verification, POST /messages/revoke, and the read endpoints GET /channels, GET /senders, GET /balance, GET /edrs.
Broadcasts Bulk campaigns and templates — POST /broadcast/broadcasts, and the /broadcast/templates endpoints (create, list, and manage by id).
Recipients Contact management — recipients, attributes, tags, filters.

Webhook resolution

The key can carry a fallback webhook URL. When the platform dispatches a status event it uses the first URL set in this order: the webhook field in the request body → the Sender’s webhookUrl → the key’s webhook. If none is set, the event is dropped and GET /edrs is the only way to retrieve it. See Webhooks & Events.

Recommendations

  • One key per integration. Scope each key to only what that integration needs.
  • Rotate by create-new-then-swap. Create a replacement key, deploy it, then delete the old one — no downtime.
  • Never log or embed keys in client-side code or version control.

Sender binding

Keys authenticate the request; the Sender ID in the request body determines the visible originator. A send is rejected if the Sender ID is not Active or not permitted for the account behind the key.