SMS GatewayDocumentation

Authentication

The SMS Gateway API supports two authentication methods: API Keys for SMS API access and JWT Bearer Tokens for dashboard and management operations. All requests must be authenticated.

Overview

API Key Authentication

Best for server-to-server communication. Use for all SMS API endpoints including sending messages, checking status, and OTP operations.

Bearer Token

JWT Token Authentication

Best for dashboard integrations and management APIs. Provides short-lived access with refresh token rotation.

OAuth 2.0

API Key Authentication

API keys are long-lived credentials that authenticate your server-side requests to the SMS API. Each key is scoped to specific permissions and can optionally be restricted to a set of allowed IP addresses.

Generating an API Key

  1. Navigate to Developer → API Keys in the dashboard.
  2. Click Generate New Key.
  3. Enter a descriptive name (e.g., “Production SMS”).
  4. Select the required permission scopes.
  5. Optionally add IP address restrictions for enhanced security.
  6. Click Create and copy the generated key.

Using the API Key

Include the API key in the Authorization header of every request using the Bearer scheme:

Authorization header
1Authorization: Bearer sg_live_xxxxxxxxxxxx
Example: Send SMS with API Key
1curl -X POST https://api.smsgateway.com/api/v1/sms/send \
2  -H "Authorization: Bearer sg_live_xxxxxxxxxxxx" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "to": "+251911234567",
6    "body": "Hello from SMS Gateway!"
7  }'

Security Best Practices

Store securely: Keep API keys in environment variables or a secrets manager. Never commit them to source control.

Use IP restrictions: Limit key usage to your server IP addresses to prevent unauthorized access.

Apply least privilege: Only grant the permission scopes your application needs.

Rotate regularly: Rotate keys periodically and immediately if a compromise is suspected.

Monitor usage: Review API logs in the dashboard to detect unusual activity.

Key Prefixes

PrefixEnvironmentDescription
sg_live_ProductionLive API key — messages are billed and delivered.
sg_test_SandboxTest API key — messages are simulated, not delivered.