AUTHENTICATION

Authentication

All API requests must be authenticated. SMS Gateway supports OAuth2 client credentials (recommended) and API key authentication.

OAuth2 Client Credentials (Recommended)

The most secure authentication method. Exchange your client credentials for a short-lived Bearer token, then use it for all API requests.

1. Request an Access Token

POST /api/v1/auth/token

No authentication required for this endpoint.

Parameter	Type	Required	Description
client_id	string	Required	Your client ID
client_secret	string	Required	Your client secret
grant_type	string	Required	Must be "client_credentials"

Request a token

curl -X POST "https://api.yourdomain.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "client_abc123def456",
    "client_secret": "secret_xyz789uvw012",
    "grant_type": "client_credentials"
  }'

Response — 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

2. Use the Token

Include the token in the Authorization header of all subsequent requests:

Using the Bearer token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Lifecycle

Tokens expire after 1 hour (3600 seconds)
The expires_in field tells you when to refresh
Request a new token before the current one expires
Implement automatic refresh in your application

API Key Authentication (Legacy)

Not recommended for new integrations

API keys do not support token expiration, granular permissions, or audit logging. Use OAuth2 for maximum security.

For simple or legacy integrations, you can use your API key (starts with sk-) directly as a Bearer token:

API key as Bearer token

Authorization: Bearer sk-your-api-key-here

SDK Example: Python

auth_example.py

import requests
import time

class SMSGatewayClient:
    def __init__(self, client_id, client_secret, base_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = base_url
        self.access_token = None
        self.token_expiry = 0

    def authenticate(self):
        """Get access token"""
        url = f"{self.base_url}/api/v1/auth/token"
        payload = {
            "client_id": self.client_id,
            "client_secret": self.client_secret,
            "grant_type": "client_credentials"
        }
        response = requests.post(url, json=payload)
        response.raise_for_status()
        data = response.json()
        self.access_token = data["access_token"]
        self.token_expiry = time.time() + data["expires_in"] - 60
        return self.access_token

    def get_token(self):
        """Get valid access token, refreshing if needed"""
        if not self.access_token or time.time() >= self.token_expiry:
            self.authenticate()
        return self.access_token

    def send_sms(self, to, message, **kwargs):
        """Send single SMS"""
        url = f"{self.base_url}/api/v1/sms/send"
        headers = {
            "Authorization": f"Bearer {self.get_token()}",
            "Content-Type": "application/json"
        }
        payload = {"to": to, "message": message, **kwargs}
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        return response.json()

# Usage
client = SMSGatewayClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
    base_url="https://api.yourdomain.com"
)
result = client.send_sms("+265888123456", "Hello!")
print(result)