API Gateway and WAF Reference Architecture: Ownership, Header Trust, and Failure Modes

An API gateway and a web application firewall (WAF) solve different parts of the API security problem. The gateway owns API identity, routing, quotas, and service-aware policy. The WAF inspects HTTP traffic for exploit patterns and applies a managed rule set. A sound design makes both controls explicit, prevents clients from bypassing either one, and decides what happens when inspection is slow or unavailable.

Do not treat “put a WAF in front of the gateway” as a complete architecture. You must also define the only permitted request path, which component establishes the client IP, what content can be inspected, how duplicate controls interact, and whether each route fails open or closed.

Key Takeaways

Give the WAF exploit inspection and the gateway API identity, authorization, routing, and quota enforcement.
Accept forwarding headers only from explicitly trusted proxies, then replace rather than append security-sensitive context.
Restrict the gateway or origin so clients cannot reach it around the WAF.
Choose fail-open or fail-closed per route and threat model; test the choice under timeout, overload, and partial failure.
Start in monitor mode, tune against representative traffic, and promote rules with observable rollback.

Divide Control Ownership

Decision	Primary owner	Why
Known HTTP exploit signatures	WAF	Rule engines are built to inspect request components and update attack rules
Token validation and client identity	API gateway or identity-aware service	Identity needs issuer, audience, signature, and route context
Route and method authorization	API gateway plus application	The gateway can reject coarse policy; the application retains object-state checks
Rate and concurrency policy	API gateway	Limits often depend on route, consumer, tenant, or service capacity
Schema and business invariants	Gateway validator and application	A WAF rule set does not know the complete API contract or domain state
Vulnerability remediation	Application owner	Filtering is a compensating control, not a code fix

The OWASP API Security Top 10 includes risks such as broken object authorization and unrestricted resource consumption. A generic WAF cannot infer object ownership or a tenant's capacity budget. Keep those controls in the gateway and application even when the WAF blocks injection payloads.

Choose a Traffic Topology

Edge WAF before the gateway

flowchart LR
    C[Client] --> W[Edge WAF]
    W --> G[API gateway]
    G --> A[API service]

This pattern centralizes public filtering and can absorb unwanted traffic before it reaches the gateway. Its security condition is strict: the gateway must accept public traffic only from the WAF path. Use private networking, origin access controls, firewall rules, or authenticated origin connections. A public gateway hostname that remains reachable directly turns the WAF into an optional hop.

Gateway-integrated WAF service

flowchart LR
    C[Client] --> G[API gateway]
    G -->|Inspection request| W[WAF service]
    W -->|pass or reject| G
    G -->|Apply configured monitor or block mode| O[Continue to API or deny request]

This pattern lets the gateway select inspection by route and attach normalized context. It also puts WAF latency and availability in the request path. Apache APISIX documents this model with the chaitin-waf plugin, which connects to SafeLine nodes. SafeLine returns a pass or reject decision; APISIX then applies the configured plugin mode. In monitor mode, a rejection is logged but the request is not blocked. In block mode, the rejection blocks the request. The integration is an example, not proof that every WAF has the same contract.

Avoid running both topologies with identical rules by default. Double inspection adds latency and can produce conflicting block decisions. If two layers are required, document their distinct scopes—for example, edge rules for broad internet threats and route-specific inspection close to API context.

Establish a Trusted Header Contract

Every proxy hop can add or rewrite Forwarded, X-Forwarded-For, X-Forwarded-Proto, host, and correlation headers. If the gateway trusts these values from any client, IP restrictions, audit records, redirects, and WAF exceptions can be wrong.

Define the contract in order:

List every trusted proxy or load-balancer address range.
At the first trusted hop, discard client-supplied values for security-sensitive forwarding fields.
Create normalized client IP, scheme, host, and request ID values.
Configure the next hop to trust those values only when the immediate peer is trusted.
Forward only the context that the application needs.

The current APISIX chaitin-waf documentation states that when real_client_ip is enabled, as it is by default, the plugin sends APISIX's resolved client IP, derived from connection information and apisix.trusted_addresses. When real_client_ip is disabled, the plugin sends the IP of the peer directly connected to APISIX. Treat this setting as part of the security boundary, not a convenience. Test direct connections with forged forwarding headers and confirm that WAF, gateway, and application logs agree on the client context.

Define Inspection and Privacy Boundaries

Write down which parts of a request the WAF receives: headers, query strings, path, body, and maximum body size. Then classify the data. Authorization headers, cookies, personal data, file uploads, and payment fields can enter WAF logs or diagnostics if redaction is incomplete.

Set bounded body and timeout limits. A body that exceeds the inspection limit needs a documented outcome: reject, inspect metadata only, route to a specialized upload path, or accept with a recorded exception. Encrypted or compressed application payloads may be opaque even after TLS termination. “Passed the WAF” therefore means only that the inspected representation did not trigger the active rules.

Decide Failure Behavior by Route

There is no universal answer to a WAF outage.

Route class	Common starting point	Required qualification
Public read with low data sensitivity	Bounded fail-open may be considered	Apply gateway identity and rate limits; alert immediately; cap duration
Login, payment, administration, or write	Fail closed or return a distinct service error	Isolate WAF capacity and test recovery so an outage does not become prolonged downtime
Health and internal control endpoints	Explicit bypass only when necessary	Restrict by network and identity; never inherit a broad wildcard exception

Differentiate a malicious-request block from an inspection infrastructure failure. Clients and operators need distinct status, reason code, metric, and log fields. Bound retries; retrying inspection across an overloaded WAF pool can amplify the incident.

Roll Out Rules Safely

Use a lifecycle rather than enabling a large ruleset directly in block mode:

Inventory API methods, content types, normal body sizes, and known machine clients.
Enable monitor mode on a small route set.
Measure matches by rule ID, route, response outcome, and client class without logging secrets.
Reproduce likely false positives with sanitized test cases.
Promote a reviewed rule subset to block mode.
Canary changes and retain a fast, audited rollback.
Expire temporary exclusions and virtual patches after the application is fixed.

The OWASP Core Rule Set documentation explains that rule tuning and anomaly scoring are operational work. Lowering sensitivity globally to fix one false positive weakens unrelated routes; prefer narrow exclusions tied to a route and parameter.

Verification Plan

Test the architecture as a system:

a benign request reaches the intended upstream;
representative injection payloads are detected in monitor mode and blocked in block mode;
a direct request cannot bypass the WAF or gateway;
spoofed forwarding headers do not change the trusted client identity;
oversized and unsupported bodies follow the documented path;
WAF timeout, connection refusal, and overload produce the selected route behavior;
logs correlate one request across WAF, gateway, and service without exposing credentials;
disabling or rolling back a rule is observable and access-controlled.

Use security scanning to exercise the contract, but do not call a single scanner run proof of protection. Repeat tests after rule, proxy, TLS, route, and application changes.

Design Checklist

Is there exactly one permitted public path to the API?
Which component creates trusted client context, and which peers may supply it?
Which request fields and maximum sizes are inspected?
Which controls remain in the gateway and application?
Does every route have documented timeout and fail behavior?
Are WAF events correlated without logging secrets or full sensitive bodies?
Can rules be monitored, canaried, rolled back, and expired?
Have bypass, spoofing, overload, and recovery been tested?

Summary

A WAF and an API gateway are strongest when their responsibilities do not blur. Put exploit inspection in the WAF, keep identity and API-aware policy in the gateway, preserve business authorization in the application, and make every trust transition testable. The result is defense in depth with known limits—not a chain of appliances that silently assumes every request took the intended path.

FAQ

Does a WAF replace API authentication and authorization?

No. A WAF can reject suspicious HTTP patterns, but it usually cannot decide whether a verified principal owns a specific object or may perform a business action.

Should the WAF sit before or inside the API gateway?

Choose based on exposure, route context, latency, and operations. An edge WAF needs strong origin restriction; an integrated WAF needs a defined synchronous failure contract.

Should the integration fail open?

Only after a route-specific risk decision. A bounded fail-open path may protect availability for low-risk reads, while sensitive writes commonly need fail-closed behavior.

Next Steps

Review DDoS defense at the API gateway, define IP allowlist and denylist trust, and test the design through an API gateway security-scanning program.