Authentication
Every request carries your secret key in the x-api-key header. Keys belong to an API client inside your workspace.
The x-api-key header
Send your key in the x-api-key header on every request, over HTTPS. There are no sessions or OAuth flows on the product API.
Authenticated request
curl https://api.smsray.com/api/sms/v1/sms/balance \
-H "x-api-key: ls_live_3f9c…"API keys and clients
- A key looks like
ls_live_followed by 48 hex characters. The dashboard shows only its prefix (for examplels_live_3f9c) afterwards. - We store only a SHA-256 hash of the key. Nobody — including us — can show it to you again, so copy it when it is created.
- Each key belongs to one API client in your workspace. The client holds its own brand name, webhook URL, webhook secret, request rate and counters.
- Balance, rates and allowed message types belong to the workspace and are shared by all its clients.
- A key can only see its own messages. Looking up a message sent by another client returns 404, even inside the same workspace.
- A key can be put in test mode: requests are accepted and recorded, nothing is sent and nothing is charged.
Rotating a key
Workspace owners can rotate a client's key from the dashboard. The new key works at once and the old key stops working immediately, so deploy the new key first-thing or rotate during a quiet window. To stop a client entirely, disable it instead: its requests return 403 client_disabled and its message history stays intact.
Workspace status
| Status | GET requests | POST requests |
|---|---|---|
pending | Work | 403 workspace_pending |
active | Work | Work |
suspended | May be refused | 403 workspace_suspended |
GET /sms/balance returns workspaceStatus, so your app can check it at start-up.
Auth errors
| HTTP | code | When |
|---|---|---|
| 401 | unauthorized | "Missing x-api-key" — the header was not sent. |
| 401 | unauthorized | "Invalid API key" — the key is unknown or was rotated. |
| 403 | client_disabled | The client that owns this key is disabled. |
| 403 | workspace_pending | POST before your workspace is activated. |
| 403 | workspace_suspended | POST while your workspace is suspended. |
Good practice
- Call the API from your server only. A key in a mobile app or browser bundle can be extracted and used to spend your balance.
- Use a separate client per app and environment, so you can rotate or disable one without touching the others.
- Keep keys in environment variables or a secret manager, and out of logs and source control.
- Every change in the portal — keys created, rotated or disabled — is recorded in your workspace audit log.