Authentication

Every request to the AfriRoute API must include a valid API key. This guide covers how to create, manage, and securely use your credentials.

Overview

AfriRoute uses API-key authentication for direct developer requests. Include your API key in theX-API-Keyheader of every request. Console login and some governed flows may also issue bearer tokens, but the public API path should use scoped keys.

Sandbox Key

For testing. No charges. Prefixed with sk_test_

Production Key

For live traffic. Charges apply. Prefixed with sk_live_

Getting Your API Key

1
Sign in to the AfriRoute ConsoleOpen Console →
2
Navigate to Settings → API Keys
3
Click "Create new key" and select the environment (Sandbox or Production)
4
Copy the key immediately — it will only be shown once

Making Authenticated Requests

Include your API key in the X-API-Key header:

curl -X POST BASE_URL/api/v1/channels/sms/otp   -H "X-API-Key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2519XXXXXXXX",
      "country": "ET",
      "template": "Your verification code is 123456"
  }'

Node.js / TypeScript

import AfriRoute from 'afriroute';

const client = new AfriRoute({
  apiKey: process.env.AFRIROUTE_API_KEY,
  baseUrl: 'BASE_URL',
});

const res = await client.sms.send({
  to: '+2519XXXXXXXX',
  from: 'AfriRoute',
  text: 'Hello!',
});

Python

import afriroute

client = afriroute.Client(
    api_key="sk_test_your_key"
)

response = client.sms.send(
    to="+2519XXXXXXXX",
    from_="AfriRoute",
    text="Hello!"
)

Key Scopes & Permissions

API keys can be scoped to limit what resources they can access. Use scoped keys for each application, workflow, or integration you operate.

Scope	Access	Example Use
sms:send	Send SMS messages	OTP service
sms:read	Read message history & status	Analytics dashboard
payments:*	Full payment operations	Checkout service
voice:send	Initiate voice calls	IVR system
*	Full access (all resources)	Platform administration

Error Responses

If authentication fails, the API returns one of these HTTP status codes:

401

Unauthorized

Missing or invalid API key. Check your X-API-Key header.

403

Forbidden

Valid key but insufficient scope. The key does not have permission for this resource.

429

Rate Limited

Too many requests. Back off and retry with exponential delay.

Security Best Practices

Use environment variables

Never hardcode API keys in source code. Use .env files or a secrets manager.

Rotate keys regularly

Rotate production keys every 90 days. Revoke compromised keys immediately.

Use scoped keys

Create keys with minimal permissions. Each service should have its own key.

Monitor usage

Set up alerts for unusual API activity. Review access logs in the Console.

What's next?

Send your first message Set up webhooks Full API reference