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

ScopeAccess 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

namestringrequired: Descriptive label (e.g. 'CRM Integration').
scopesstring[]required: Array of scope strings from the table above.
expires_atISO 8601: Optional expiry. Omit for a non-expiring token.

curl -X POST "https://bulksmsapi.inline.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://bulksmsapi.inline.co.ke/api/v1/tokens" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Revoke a token

DELETE/api/v1/tokens/{uuid}

curl -X DELETE "https://bulksmsapi.inline.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.