SendComms
Dashboard
API Reference

Authentication

SendComms uses API keys to authenticate requests. You can manage your API keys in thedashboard. All API requests must include your API key in the Authorization header.

API Key Format

SendComms API keys follow a specific format to help you identify the key type:

PrefixEnvironmentDescription
sc_live_ProductionLive API key for production use
sc_test_SandboxTest key for development — returns mock responses, no charges

Authorization Header

Include your API key in the Authorization header using the Bearer token scheme:

REQUEST HEADER
Authorization: Bearer sc_live_your_api_key_here

Example Requests

Here's how to authenticate API requests in different languages:

curl -X POST https://api.sendcomms.com/api/v1/sms/send \
  -H "Authorization: Bearer sc_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233201234567",
    "message": "Hello from SendComms!"
  }'

API Key Permissions

Enforced on every request

A key may only call the services listed in its permissions. Calling a service the key does not carry returns 403 FORBIDDEN, with the required permission named in the response. Keys created today are granted all four; issue a narrower key when handing credentials to a third party so it cannot spend on data bundles or airtime.

Each key carries the services it is allowed to use:

PermissionEndpointsDescription
sms/api/v1/sms/*Send SMS messages
email/api/v1/email/*Send email messages
data/api/v1/data/*Purchase data bundles
airtime/api/v1/airtime/*Purchase airtime (coming soon)

Full Access Keys

By default, API keys created from the dashboard have access to all services. You can create restricted keys with specific permissions for better security.

Authentication Errors

When authentication fails, you'll receive one of these error responses:

401Unauthorized— Missing or invalid API key
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "docs_url": "https://docs.sendcomms.com/docs/errors#client-error-codes"
  }
}
403Account Suspended— The API key is valid, but the account behind it is suspended
{
  "success": false,
  "error": {
    "code": "ACCOUNT_SUSPENDED",
    "message": "Account suspended. Contact support.",
    "docs_url": "https://docs.sendcomms.com/docs/errors#client-error-codes"
  }
}

Security Best Practices

Store Keys Securely

We only store a SHA-256 hash of your key, so the full value is shown once at creation and can never be retrieved again — if you lose it, create a new key. Never hardcode API keys in your source code; use environment variables or a secrets manager.

Rotate Keys Regularly

Periodically rotate your API keys and immediately revoke any compromised keys from the dashboard.

Use Least Privilege

Create API keys with only the permissions needed for each use case. Don't use full-access keys everywhere.

Server-Side Only

Never expose API keys in client-side code. Make all API calls from your backend server.

Using Environment Variables

Here's the recommended way to use API keys in your application:

.env
# SendComms API Key
SENDCOMMS_API_KEY=sc_live_your_api_key_here
USAGE IN CODE
// Node.js / JavaScript
const apiKey = process.env.SENDCOMMS_API_KEY;

const response = await fetch('https://api.sendcomms.com/api/v1/sms/send', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  // ...
});
Quick StartRate Limits