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 |
|---|---|---|---|
| API token | opaque string | Yes | Created in the portal under Settings → API Tokens. Works on the frozen /v1/ and /v2/ SMS endpoints. This is the token most integrations use. |
| mbs_ scoped token | mbs_… | Yes | Also created under Settings → API Tokens, with explicit scopes (e.g. WhatsApp send). Required for the newer /api/v1/ platform resources. Stored hashed on our side — copy it when created; it is never shown again. |
| 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 API or 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 → Settings → 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.