Authentication
Every request needs an API key in the Authorization header:
Authorization: Bearer cm_live_0123456789abcdefABCDEFexample0
A missing, unknown, expired or revoked key returns 401 invalid_api_key.
Live and test keys
| Prefix | Environment | What happens |
|---|---|---|
cm_live_ | Live | Real SMS to real phones. Uses SMS units. |
cm_test_ | Sandbox | Nothing is sent, no units are used. See Sandbox. |
Both work against the same URL, https://api.cloudmetis.com/v1. Switching from test to live is only a key change.
Creating a key
Keys are created in the app under Management → Developer API by an organisation admin. Other members can see the list of keys (prefix only) but cannot create, change or revoke them.
When you create a key you choose:
- Name — e.g. "Production server", so you can tell keys apart.
- Environment — live or test.
- Permissions — see below.
- Expiry (optional) — the key stops working after this date.
- Webhook URL (optional) — the default address for delivery reports. See Webhooks.
The full key and its webhook secret are shown once. CloudMetis stores only a fingerprint (hash) of the key, so it cannot be shown again — if you lose it, roll the key.
An organisation can have up to 10 active keys, and create up to 5 keys per hour.
Permissions (scopes)
| Scope | Allows |
|---|---|
sms:send | POST /v1/sms/send |
sms:read | GET /v1/sms/status/{message_id}, GET /v1/sms/batches/{batch_id} |
wallet:read | GET /v1/sms/balance |
New keys get all three. Give a key only what it needs — a reporting job, for example, only needs sms:read. Calling an endpoint without its scope returns 403 scope_denied.
Rolling a key
Use Roll in Developer API to replace a key, for routine rotation or when a key may have leaked. Rolling creates a new key with the same name, environment, permissions, expiry and webhook URL — and the same webhook secret, so your webhook receiver keeps working.
You choose when the old key stops working:
| Option | Use when |
|---|---|
| Immediately | The key leaked. |
| In 1 hour / 24 hours / 7 days | Routine rotation — time to deploy the new key first. |
During the grace period both keys work.
Revoking a key
Revoke stops a key immediately and permanently. Any system still using it gets 401.
Keeping keys safe
- Keep keys on your server, in environment variables or a secrets manager. Never put them in a mobile app, browser JavaScript or a public repository.
- Use a separate key per system, so you can revoke one without affecting the others.
- Last used time and IP in Developer API help you spot keys you no longer need.