SMS GatewayDocumentation

API Keys

API keys authenticate your requests to the SMS Gateway. Each key can have granular permissions and restrictions for secure access control.

Overview

API keys are credentials that allow you to authenticate programmatic access to the SMS Gateway API. Each key is associated with your organization and can be scoped with specific permissions, IP restrictions, and expiration dates.

Your full API key is only shown once at creation time. Store it securely and never expose it in client-side code or version control.

Key Format

API keys follow a standardized format with environment prefixes:

Production
sg_live_xxxxxxxxxxxx

Use for live traffic. Requests count toward your billing and send real messages.

Sandbox
sg_test_xxxxxxxxxxxx

Use for testing. Requests are simulated and do not incur charges.

Available Endpoints

GET
/api/v1/developer/api-keysList all API keys
GET
/api/v1/developer/api-keys/:idGet key details
POST
/api/v1/developer/api-keysCreate new key
PATCH
/api/v1/developer/api-keys/:idUpdate key
POST
/api/v1/developer/api-keys/:id/regenerateRegenerate key value
POST
/api/v1/developer/api-keys/:id/enableEnable key
POST
/api/v1/developer/api-keys/:id/disableDisable key
DELETE
/api/v1/developer/api-keys/:idDelete key

Create an API Key

Send a POST request with the following body to create a new API key.

Request Body

name
required
string — A descriptive name for the key.
description
optional
string — Additional description of the key's purpose.
permissions
optional
string[] — Granular permissions (e.g. ["sms.send", "sms.read"]).
expiresIn
optional
string — Expiration duration (e.g. "30d", "90d").
ipRestrictions
optional
string[] — Allowed IP addresses or CIDR ranges.
create-key.json
1{
2  "name": "Production Server",
3  "description": "API key for production SMS sending",
4  "permissions": ["sms.send", "sms.read"],
5  "expiresIn": "90d",
6  "ipRestrictions": ["192.168.1.1", "10.0.0.0/8"]
7}

List API Keys

list-keys.json
1[
2  {
3    "id": "key_abc123def",
4    "name": "Production Server",
5    "keyPrefix": "sk_4f2a1b9c...",
6    "permissions": ["sms.send", "sms.read"],
7    "isActive": true,
8    "createdAt": "2025-01-10T08:00:00.000Z",
9    "lastUsedAt": "2025-01-15T09:30:00.000Z",
10    "expiresAt": "2025-04-10T08:00:00.000Z"
11  },
12  {
13    "id": "key_ghi456jkl",
14    "name": "CI/CD Pipeline",
15    "keyPrefix": "sk_8d3e2f0a...",
16    "permissions": ["sms.send"],
17    "isActive": true,
18    "createdAt": "2025-01-12T14:00:00.000Z",
19    "lastUsedAt": null,
20    "expiresAt": null
21  }
22]

Regenerate Key

Regenerating a key creates a new secret value while preserving the key's ID, name, and configuration. The old value is immediately invalidated.

regenerate-key.json
1{
2  "id": "key_abc123def"
3}
4// Response:
5{
6  "id": "key_abc123def",
7  "name": "Production Server",
8  "rawKey": "sk_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
9  "keyPrefix": "sk_abc123def..."
10}

Available Permissions

sms.sendSend single and bulk SMS messages
sms.readRead message history and delivery status
otp.sendGenerate and send OTP codes
otp.verifyVerify OTP codes
contacts.readRead contact lists
contacts.writeCreate and manage contacts
campaigns.manageCreate and manage campaigns
analytics.readAccess analytics data
webhooks.manageManage webhook endpoints

Security Best Practices

Rotate Regularly

Rotate API keys periodically (every 90 days recommended) to limit exposure from potential credential leaks.

Use IP Restrictions

Restrict keys to known IP addresses to prevent unauthorized use even if the key is compromised.

Least Privilege

Grant only the minimum permissions required for each key's intended use case.

Monitor Usage

Regularly review key usage in the Developer Portal and revoke unused or suspicious keys.

Related Pages

IP Whitelist

Restrict API access to specific IP addresses.

Rate Limits

Understand and configure rate limits per API key.