Getting Started

API Authentication

Learn how to use Basic Authentication for secure access to Statum APIs including M-Pesa, Airtime, and SMS. Protect your credentials with HTTPS and generate secure API keys.

Securing your API integration is paramount. All Statum communication and payment services, including Airtime, SMS, and M-Pesa APIs, require robust authentication to protect your organization's data and wallet balance. Our gateway utilizes Basic Authentication (HTTP Basic Auth), a widely supported and secure industry standard.

To begin, you will need to generate your API credentials (Consumer Key and Consumer Secret) via the Statum developer dashboard. These credentials act as your master keys for API access.

How Basic Authentication Works

Basic Authentication is a simple, built-in HTTP authentication method. Your client sends an Authorization header containing the word Basic followed by a space and a base64-encoded string of your consumerKey:consumerSecret.

Authorization: Basic dG9wc2VjcmV0OjEyMzQ=

Step-by-Step Authentication Procedure

  1. Concatenate your consumerKey and consumerSecret with a colon (:).
    Example: admin:admin
  2. Encode the string using base64 encoding.
  3. Include the encoded string in your HTTP request header:
    Example: Authorization: Basic YWRtaW46YWRtaW4=

Generate base64 headers easily in your preferred programming language. See this GitHub Gist for sample code.

Sample API Request

Use the following examples to understand how to construct an authenticated request. We've included examples for cURL, PHP, and Node.js.

Authenticate Request 
# Replace with your actual credentials
                consumer_key="568473daf6614cb196caeb5f8805985f"
                consumer_secret="5a07f41de16e40e4b08b4001142a5a10"

                # Create the Base64 encoded signature
                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",
                "message": "Hello from Statum!"
                }'
<?php

                $consumerKey = "568473daf6614cb196caeb5f8805985f";
                $consumerSecret = "5a07f41de16e40e4b08b4001142a5a10";

                // 1. Construct the signature
                $credentials = base64_encode($consumerKey . ":" . $consumerSecret);

                $curl = curl_init();

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

                $response = curl_exec($curl);
                $err = curl_error($curl);

                curl_close($curl);

                if ($err) {
                echo "cURL Error #:" . $err;
                } else {
                echo $response;
                }
                ?>
const axios = require('axios');

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

                let config = {
                method: 'post',
                url: 'https://api.statum.co.ke/api/v1/sms/send',
                headers: {
                'Authorization': `Basic ${credentials}`,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
                },
                data: {
                "phone_number": "254712345678",
                "message": "Hello from Statum!"
                }
                };

                axios(config)
                .then((response) => {
                console.log(JSON.stringify(response.data));
                })
                .catch((error) => {
                console.log(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\", \"message\":\"Hello from Statum!\"}");

                Request request = new Request.Builder()
                .url("https://api.statum.co.ke/api/v1/sms/send")
                .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

Encountering issues? Use the status code to diagnose the problem.

401 Unauthorized

Invalid Credentials

Your Consumer Key or Secret is incorrect, or the Base64 encoding is malformed. Double-check your matching credentials from the dashboard.

403 Forbidden

Access Denied

Credentials are valid, but access is restricted.

  • Account suspended or inactive
  • IP address not whitelisted
  • Service/Product not enabled

Security Best Practices

Related Developer Resources