Skip to main content
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 Parameters

ParameterTypeDescriptionRequiredDefault
enabledbooleanEnables or disables enforcementNofalse
ipsarrayExact IP addresses to allow (e.g., "203.0.113.5")Cond.[]
cidrsarrayAllowed CIDR ranges (e.g., "203.0.113.0/24")Cond.[]
Validation notes:
  • When enabled is true, provide at least one of ips or cidrs.
  • Each IP must be a valid IPv4/IPv6 address; each CIDR must be a valid IPv4/IPv6 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