Getting Started

API Authentication Guide

Learn how to authenticate requests to the Statum gateway using HTTP Basic Authentication. Secure your M-Pesa, Airtime, and Bulk SMS API integrations.

This API Authentication Guide explains how your server should identify itself when calling the Statum gateway. The same approach is used for the M-Pesa, SMS, and airtime services documented here: HTTP Basic Authentication with a Consumer Key and Consumer Secret.

Before making a request, sign in to the Statum developer portal and generate a Consumer Key and Consumer Secret. Keep both values on your server and do not place them in browser code or public repositories.

How Basic Authentication Works

For Basic Authentication, join the consumerKey and consumerSecret with a colon, Base64-encode the resulting string, and place it after Basic in the Authorization header.

Authorization: Basic dG9wc2VjcmV0OjEyMzQ=

Build the Authorization value

  1. Combine your Consumer Key and Consumer Secret with a colon separator.
    Format: consumerKey:consumerSecret
  2. Convert the combined string into a Base64-encoded string.
  3. Incorporate the output into your HTTP request header as:
    Authorization: Basic <Base64_String>

Many HTTP clients, including Guzzle, Axios, and OkHttp, can create this header when you provide a username and password. If you build it yourself, make sure the value is encoded once and that the request is sent over HTTPS.

Authentication Implementation Examples

The examples below show the same header in several languages. Adapt the surrounding request to the service and payload you are calling.

Authenticate Request 
# Base64 encode credentials locally
consumer_key="568473daf6614cb196caeb5f8805985f"
consumer_secret="5a07f41de16e40e4b08b4001142a5a10"
credentials=$(echo -n "$consumer_key:$consumer_secret" | base64)

curl -X POST https://api.statum.co.ke/api/v2/sms \
  -H "Authorization: Basic $credentials" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone_number": "254712345678",
    "sender_id": "Statum",
    "message": "Hello from Statum!"
  }'
<?php
$consumerKey = "568473daf6614cb196caeb5f8805985f";
$consumerSecret = "5a07f41de16e40e4b08b4001142a5a10";
$credentials = base64_encode($consumerKey . ":" . $consumerSecret);

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.statum.co.ke/api/v2/sms",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode([
        "phone_number" => "254712345678",
        "sender_id" => "Statum",
        "message" => "Hello from Statum!"
    ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Basic " . $credentials,
        "Content-Type: application/json",
        "Accept: application/json"
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
const axios = require('axios');

const consumerKey = "568473daf6614cb196caeb5f8805985f";
const consumerSecret = "5a07f41de16e40e4b08b4001142a5a10";
const credentials = Buffer.from(`${consumerKey}:${consumerSecret}`).toString('base64');

axios.post('https://api.statum.co.ke/api/v2/sms', {
    phone_number: "254712345678",
    sender_id: "Statum",
    message: "Hello from Statum!"
}, {
    headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
import okhttp3.*;
import java.util.Base64;
import java.io.IOException;

public class Main {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        String consumerKey = "568473daf6614cb196caeb5f8805985f";
        String consumerSecret = "5a07f41de16e40e4b08b4001142a5a10";
        String credentials = Base64.getEncoder().encodeToString((consumerKey + ":" + consumerSecret).getBytes());

        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\"phone_number\":\"254712345678\", \"sender_id\":\"Statum\", \"message\":\"Hello from Statum!\"}");

        Request request = new Request.Builder()
            .url("https://api.statum.co.ke/api/v2/sms")
            .post(body)
            .addHeader("Authorization", "Basic " + credentials)
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}

Troubleshooting Authentication Failures

If the header is missing, malformed, or contains credentials that do not match the account, the gateway rejects the request. Check the following cases first:

401 Unauthorized

Invalid Credentials or Base64 String

The credentials could not be validated. Check for:

  • Spaces or newline characters in your Base64 encoded string.
  • Mismatched Consumer Key or Secret.
  • Omission of the Basic prefix in the header.
403 Forbidden

Service Restricted

The credentials are valid, but authorization is denied:

  • Your account balance has been locked or suspended.
  • IP address restriction is active and your server IP is not whitelisted.
  • The requested service (e.g. SMS or Airtime) is disabled on your dashboard profile.

Security Best Practices