IP Whitelisting

Production - PATCH /api/v1/api-keys/{keyId}/ip-whitelist

IP whitelisting restricts API key usage to specific IP addresses or CIDR blocks. Requests from non-whitelisted IPs are rejected during key validation.

6.6.6Managing IP Whitelist

Update Whitelist

curl -X PATCH http://localhost:8081/api/v1/api-keys/15/ip-whitelist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "ipWhitelist": [
      "10.0.0.0/8",
      "172.16.0.0/12",
      "203.0.113.50"
    ]
  }'

IP Validation Logic

public boolean isIpAllowed(String ipAddress) {
    if (ipWhitelist == null || ipWhitelist.isEmpty()) {
        return true;  // No whitelist = all IPs allowed
    }
    for (String allowed : ipWhitelist.split(",")) {
        String trimmed = allowed.trim();
        if (ipAddress.equals(trimmed) || trimmed.equals("0.0.0.0/0")) {
            return true;
        }
        // Basic CIDR prefix matching
        if (trimmed.contains("/")) {
            String prefix = trimmed.split("/")[0];
            if (ipAddress.startsWith(prefix.substring(0, prefix.lastIndexOf('.')))) {
                return true;
            }
        }
    }
    return false;
}

Clear Whitelist

To remove all IP restrictions, send an empty set:

curl -X PATCH http://localhost:8081/api/v1/api-keys/15/ip-whitelist \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{ "ipWhitelist": [] }'

Best Practices

Always use IP whitelisting for production service keys
Use CIDR blocks for internal network ranges (e.g., 10.0.0.0/8 for private networks)
The wildcard 0.0.0.0/0 allows all IPs and effectively disables whitelisting
IP validation occurs during the validateApiKey endpoint call

Scopes & Limits Overview