IP Whitelist

Restrict API access to specific IP addresses for enhanced security. When enabled, only requests from whitelisted IPs will be accepted.

Overview

IP whitelisting adds an additional layer of security to your API access. When you add IP addresses to the whitelist, all API requests from non-whitelisted IPs will be rejected with a 403 Forbidden response.

IP whitelisting works independently of API key IP restrictions. If both are enabled, a request must pass both checks to be accepted.

Available Endpoints

GET

/api/v1/developer/ip-whitelistList all whitelisted IPs

POST

/api/v1/developer/ip-whitelistAdd IP to whitelist

PATCH

/api/v1/developer/ip-whitelist/:idUpdate whitelist entry

DELETE

/api/v1/developer/ip-whitelist/:idRemove IP from whitelist

Add IP to Whitelist

Request Body

ip

required

string — IP address or CIDR range (e.g. "192.168.1.1" or "10.0.0.0/8").

label

optional

string — A descriptive label (e.g. "Office IP").

add-ip.sh

1curl -X POST https://api.smsgateway.com/api/v1/developer/ip-whitelist \
2  -H "Authorization: Bearer <jwt_token>“ \
3  -H "Content-Type: application/json" \
4  -d '{
5    "ip": "192.168.1.1",
6    "label": "Office IP"
7  }'

single-ip.json

1{
2  "ip": "192.168.1.1",
3  "label": "Office IP"
4}

cidr-range.json

1{
2  "ip": "10.0.0.0/8",
3  "label": "Internal Network"
4}

List Whitelisted IPs

list-ips.json

1[
2  {
3    "id": "ip_abc123",
4    "ip": "192.168.1.1",
5    "label": "Office IP",
6    "isActive": true,
7    "createdAt": "2025-01-10T08:00:00.000Z"
8  },
9  {
10    "id": "ip_def456",
11    "ip": "10.0.0.0/8",
12    "label": "Internal Network",
13    "isActive": true,
14    "createdAt": "2025-01-12T14:00:00.000Z"
15  },
16  {
17    "id": "ip_ghi789",
18    "ip": "203.0.113.50",
19    "label": "CI/CD Server",
20    "isActive": false,
21    "createdAt": "2025-01-14T09:00:00.000Z"
22  }
23]

How IP Whitelist Interacts with API Keys

IP restrictions can be applied at two levels, and both are enforced when enabled:

Organization IP Whitelist

Applied to all API requests

All requests to the API must originate from a whitelisted IP, regardless of which API key is used. This is a global restriction for your organization.

Per-Key IP Restrictions

Applied to individual API keys

Individual API keys can have their own IP restrictions. A request must come from an IP allowed by both the organization whitelist and the specific key's restrictions.

Evaluation order: Organization whitelist â†’ Key restrictions â†’ Request processed. If either check fails, the request is rejected.

Enabling and Disabling Entries

You can temporarily disable a whitelist entry without deleting it. Disabled entries are skipped during IP validation.

bash

1curl -X PATCH https://api.smsgateway.com/api/v1/developer/ip-whitelist/ip_abc123 \
2  -H "Authorization: Bearer <jwt_token>" \
3  -H "Content-Type: application/json" \
4  -d '{ "isActive": false }'

Security Recommendations

Use CIDR Ranges

For office or cloud environments, use CIDR ranges instead of individual IPs to cover dynamic IP pools.

Label Entries

Always add descriptive labels to identify where each IP is used (e.g. "AWS Production", "Office VPN").

Review Regularly

Periodically audit your whitelist to remove entries for decommissioned servers or services.

Test Before Enabling

Verify your servers' IPs are whitelisted before enabling the feature to avoid locking yourself out.

API Keys

Manage API keys with per-key IP restrictions.

Error Codes

403 Forbidden error responses from IP restrictions.