Authentication & tokens
Every API call authenticates with a Bearer token in the Authorization header. Which kind of token you use depends on which part of the API you're calling.
The one header you always send
Request header
Authorization: Bearer YOUR_TOKENToken types
Which token where
| Field | Type | Required | Description |
|---|---|---|---|
| mbs_ scoped token | mbs_… | Yes | Created in the portal under API Tokens in the sidebar, with explicit scopes. Works on every endpoint in these docs: the /v1/ and /v2/ SMS routes and the /api/v1/ platform resources, provided it carries the matching scope (e.g. Send messages for the send endpoints). This is the token new integrations should use. Stored hashed on our side. Copy it when created; it is never shown again. |
| Legacy API token | opaque string | No | Pre-existing tokens issued by the old platform. Still fully supported on the frozen /v1/ and /v2/ endpoints. Existing integrations need no changes, but new ones can no longer be created. |
| JWT (session) | signed JWT | No | Issued when a user signs in to the portal. It is a browser session credential; don't build server integrations on it; use an mbs_ token instead. |
Legacy query-parameter auth
On /v1/ and /v2/ routes only, the token may also be passed as a query parameter for clients that cannot set headers:
bash
curl "https://api.mobilesasa.com/v1/get-balance/?api_token=YOUR_API_TOKEN"Prefer the header
Query strings end up in server logs and proxies. Use the
Authorization header unless your platform genuinely cannot set one.Creating an mbs_ token with scopes
- Portal sidebar → API Tokens → New token.
- Pick the scopes the integration needs. Least privilege wins. A token that only sends WhatsApp templates can't touch your contacts.
- Optionally set an expiry. Copy the
mbs_…value once, store it in your secret manager.
Rotating and revoking
Tokens can be revoked instantly from the same portal page. Revocation takes effect within seconds across the platform. For zero-downtime rotation: create the new token, deploy it, then revoke the old one.
Common auth failures
401/responseCode 0401: missing, mistyped, expired or revoked token. Check for a stray newline or the wordBearerappearing twice.403: the token is valid but lacks the scope or permission for that endpoint.
Full response semantics live in Responses & errors.