Authentication

API tokens are the recommended way to authenticate server-to-server integrations.

Tokens start with mbs_ and can be sent either way:

http

Authorization: Bearer mbs_your_token_here
# or
X-API-Key: mbs_your_token_here

Create tokens from the dashboard under Settings → API tokens, or via the API below. Each token is limited to the scopes you grant it.

Scopes

Scope	Access granted
messages	Send and retrieve SMS messages
contacts	Create, read, update, delete contacts
groups	Manage contact groups and memberships
campaigns	Create, send, and manage bulk campaigns
surveys	Read survey definitions and retrieve responses
ussd	Read USSD codes and extension info
reports	Read usage reports and daily statistics
api_tokens	Programmatically manage tokens (create / revoke)

Create a token

POST/api/v1/tokens

Parameters

namereq

string

Descriptive label (e.g. 'CRM Integration').

scopesreq

string[]

Array of scope strings from the table above.

expires_at

ISO 8601

Optional expiry. Omit for a non-expiring token.

curl -X POST "https://timisha-solutions-api.salamu.co.ke/api/v1/tokens" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "CRM Integration",
  "scopes": [
    "messages",
    "contacts",
    "groups"
  ],
  "expires_at": "2027-12-31T23:59:59Z"
}'

200: Created

{
  "success": true,
  "data": {
    "raw_token": "mbs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token": {
      "uuid": "tok-uuid",
      "name": "CRM Integration",
      "scopes": ["messages", "contacts", "groups"],
      "expires_at": "2027-12-31T23:59:59Z",
      "created_at": "2026-05-11T09:00:00Z"
    }
  }
}

Store raw_token immediately

The raw_token is shown only once and cannot be retrieved again. Later calls return only the token metadata.

List tokens

GET/api/v1/tokens

curl -X GET "https://timisha-solutions-api.salamu.co.ke/api/v1/tokens" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Revoke a token

DELETE/api/v1/tokens/{uuid}

curl -X DELETE "https://timisha-solutions-api.salamu.co.ke/api/v1/tokens/tok-uuid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Prefer tokens over JWTs

You can also authenticate with a JWT from a user login, but API tokens are scoped, revocable, and built for integrations. Use them for anything server-side.