API Gateway IP Allowlist and Denylist Management: Trust, Proxies, and Operations

An IP allowlist or denylist is only as reliable as the address the API gateway evaluates. Establish the trusted proxy path first, accept forwarded addresses only from known hops, and then apply the list. Use allowlists for small, controlled populations where default-deny is practical; use denylists as a targeted response layer, not as complete identity or authorization.

IP rules are network context. They do not prove which human, workload, or tenant is making a request, and they become less precise behind NAT, carrier networks, forward proxies, IPv6 privacy addresses, and changing cloud ranges.

Key Takeaways

• Never trust X-Forwarded-For merely because it exists.
• Make the first trusted proxy overwrite untrusted forwarding headers and configure the exact trusted proxy ranges.
• Prefer an allowlist for private administration and fixed partner ingress; use a denylist for bounded threats with an owner and expiry.
• Treat CIDR changes as production changes with review, staging, rollback, and audit evidence.
• Combine IP policy with authentication, authorization, rate limits, and monitoring.

Establish the Address Trust Boundary

The direct TCP peer may be a CDN, load balancer, ingress proxy, service mesh sidecar, or client. A forwarding header can carry the original address, but a client connected directly to an unprotected listener can also write that header.

Apache APISIX's security threat model treats request headers as attacker-controlled input unless the deployment establishes trust. A safe design answers:

1. Which component is the first trusted hop?
2. Does it remove inbound forwarding headers before setting its own?
3. Which exact address ranges can connect from that component?
4. How are multiple proxy hops interpreted?
5. Can traffic bypass the proxy and reach APISIX directly?

If the bypass path remains open, a correct header-parsing rule cannot restore trust.

Allowlist or Denylist?

An allowlist uses a small set of known-good networks and rejects everything else. This strong default is practical only when the caller population is controlled. A public API cannot usually enumerate every legitimate mobile or residential address.

A denylist preserves public reachability, but it is reactive. It should have a reason, evidence, owner, scope, and expiry. Large permanent lists can increase operational complexity and still miss distributed abuse.

Restore the Client Address in APISIX

The APISIX real-ip plugin can derive the client address from a configured request header, but only trusted proxy addresses should be allowed to influence it. The Apache APISIX 3.18 implementation requires a build that includes APISIX-Runtime to change the live client address; without that runtime support, the plugin returns 501. If your distribution does not include APISIX-Runtime, restore the address at the trusted proxy or through a supported NGINX real-IP configuration before applying ip-restriction.

The following Apache APISIX 3.18 excerpt assumes that runtime requirement is met and that 10.20.0.0/16 and 192.0.2.10 are the exact internal proxy sources in this deployment:

{
  "plugins": {
    "real-ip": {
      "source": "http_x_forwarded_for",
      "trusted_addresses": [
        "10.20.0.0/16",
        "192.0.2.10"
      ],
      "recursive": true
    },
    "ip-restriction": {
      "whitelist": [
        "198.51.100.0/24",
        "2001:db8:1200::/48"
      ],
      "message": "Source network is not allowed"
    }
  }
}

The documentation explains how recursive walks the forwarded chain. Do not copy these documentation ranges into production. Inventory your proxy topology and use your actual internal ranges. If only one trusted proxy supplies one address, prefer the simplest configuration that matches that topology.

The ip-restriction plugin supports whitelist and blacklist. Configure one policy direction for a route rather than creating ambiguous overlapping intent. Test both IPv4 and IPv6 if clients can use either.

Choose the Right Scope

Attach an IP policy to the narrowest object that owns the requirement:

• protect the APISIX Admin API at the network layer and keep it off the public data-plane listener;
• place a partner allowlist on the partner route or service, not every public route;
• constrain a sensitive operation after authentication if the source network is an additional condition;
• apply an approved edge-provider range at the origin boundary to prevent direct bypass;
• keep emergency blocks separate from permanent architecture policy.

IP policy should not replace object-level authorization. A request from an office network can still be made by the wrong user, a compromised laptop, or an untrusted process.

Operate List Changes Safely

Use a source of truth

Store CIDRs with an owner, business purpose, ticket or incident, creation time, and expiry. For provider ranges, fetch a documented, authenticated source and validate its schema. Do not make production nodes scrape an arbitrary URL on the request path.

Validate before deployment

Parse every entry as an IP or CIDR, reject duplicates and accidental broad networks, and detect overlapping allow and deny intent. Review 0.0.0.0/0, ::/0, private ranges, and single-host masks explicitly because one character can change scope dramatically.

Roll out atomically

Add new provider ranges before removing old ones during a planned rotation. Use a canary route or gateway group, verify expected callers, and retain a known recovery path outside the changed policy. Avoid manual edits on individual nodes that create fleet drift.

Log decisions without leaking data

Record policy identifier, route, trusted derived address, action, and change version. Limit retention and access because IP addresses can be personal or security-sensitive data. Do not log authentication tokens or complete request bodies to explain a rejection.

Expire reactive blocks

Every incident denylist entry should have an expiry or review time. If a block must become permanent, move it into a separately reviewed policy with a documented rationale.

Failure Modes to Test

• A client sends a forged X-Forwarded-For directly to every reachable listener.
• A request passes through one, two, and more proxies than expected.
• The first trusted proxy omits, appends, or duplicates the address header.
• A provider introduces a new IPv4 or IPv6 range during rotation.
• A legitimate caller is behind a shared NAT with a blocked address.
• One APISIX node receives a stale policy while others receive the new version.
• An emergency rule blocks operator access or health checks.
• The policy store or configuration distribution is unavailable.

Expected outcomes should include the derived address, matching rule, response status, log event, alert, and rollback path. Test on a staging topology that mirrors the real proxy chain; a direct local request does not exercise forwarded-address trust.

Management Checklist

• Is the evaluated address the TCP peer or a forwarded value?
• Which exact proxy ranges are trusted to supply it?
• Can clients bypass the trusted proxy path?
• Is an allowlist feasible, or is a denylist only a temporary mitigation?
• Does the rule apply to the narrowest route or service?
• Are IPv4, IPv6, NAT, and shared proxies considered?
• Do entries have owners, reasons, timestamps, and expiries?
• Are updates parsed, reviewed, canaried, atomic, and reversible?
• Can operators recover if the policy locks them out?
• Are IP rules supplemented by identity and authorization?

Summary

Reliable IP restriction begins with trusted address derivation, not with a list of CIDRs. Close bypass paths, configure the exact proxy chain, then use allowlists for controlled populations and denylists for bounded response actions. Manage every change as code with scope, ownership, expiry, testing, and rollback. Finally, keep IP context in its proper role alongside authentication and authorization.

FAQ

Is X-Forwarded-For safe for an IP allowlist?

Only when the first trusted hop removes untrusted input, writes the header, and APISIX accepts it exclusively from configured trusted proxy addresses. Otherwise a client can choose the apparent source.

Should a public API use an IP allowlist?

Usually not for all callers because legitimate addresses are dynamic and shared. It can still protect administrative paths, fixed partners, or the origin-to-edge boundary.

How often should a denylist be reviewed?

At the expiry or review time assigned when each entry is created. Incident blocks should not become permanent merely because nobody removed them.

Next Steps

Pair network context with API gateway authentication and distributed rate limiting. For centralized enterprise policy operations, explore API7 Enterprise.