The IP Whitelist plugin restricts access to your routes or applications based on the caller’s IP address. Only requests coming from explicitly allowed IPs or networks (CIDR ranges) are permitted; all others are denied.

​
What it does

  • Evaluates the incoming request IP at the pre-request stage
  • Allows the request only if it matches one of the configured IPs or CIDR ranges
  • Returns 403 Forbidden otherwise
  • Can be toggled on/off via configuration

​
Configuration

Settings:
  • enabled (boolean): Enables or disables the whitelist enforcement.
  • ips (array of strings): Exact IP addresses to allow (e.g., "203.0.113.5").
  • cidrs (array of strings): Allowed CIDR ranges (e.g., "203.0.113.0/24").
Validation rules:
  • At least one of ips or cidrs must be provided when enabled is true.
  • Each IP must be a valid IPv4 or IPv6 address.
  • Each CIDR must be a valid IPv4 or IPv6 CIDR block.
Behavior notes:
  • Stage: PreRequest
  • Uses the connection fingerprint to extract the client IP
  • If the IP cannot be determined, the request is denied with 403

​
Example configuration

Add the plugin to a rule’s actions list with the desired settings: 
{
  "name": "ip_whitelist",
  "enabled": true,
  "stage": "pre_request",
  "priority": 1,
  "parallel": false,
  "settings": {
    "ips": ["203.0.113.5", "2001:db8::1"],
    "cidrs": ["203.0.113.0/24", "2001:db8::/32"],
    "enabled": true
  }
}

​
Best practices

  • Keep IP allowlists as tight as possible and review them periodically
  • Prefer CIDR ranges for corporate networks and exact IPs for fixed hosts
  • Combine with rate limiting and bot detection for stronger perimeter security
  • Log blocked attempts to monitor and investigate unauthorized access