API7 Gateway 3.10.4: Make Every Trust Boundary Explicit

A request reaches an API gateway carrying more than a method, path, and body. It can also carry a browser cookie, an end-user bearer token, identity headers, a client address supplied by a load balancer, and configuration that tells the platform where to connect next.

Some of that context is authoritative. Some is merely supplied by the caller. The difficult part is keeping the two apart as a request crosses browser, gateway, identity provider, model provider, internal service, and control-plane boundaries.

This problem becomes more urgent as API and AI traffic converge. An AI application may authenticate a user with one credential, route a prompt with another, and call a third-party model with a provider key. If the gateway forwards the wrong headers, the model provider can receive credentials that were intended only for the application. If an authentication plugin trusts caller-supplied identity headers, an upstream can receive an identity that was never established. If management features can connect to arbitrary endpoints, a configuration value can become a path into an internal service or cloud metadata endpoint.

API7 Gateway 3.10.4, released on July 27, 2026, addresses these risks by making trust decisions more explicit. The release tightens AI-provider egress, clears caller-supplied identity headers in wolf-rbac, adds an opt-in server-side request forgery (SSRF) guard for Control Plane connections, improves token forwarding for upstream verification, and defines which network peers may supply client addresses on stream traffic.

The larger lesson is not a list of security fixes. It is an architecture rule: context should cross a gateway boundary only when its origin, purpose, and next recipient are clear.

flowchart LR
    client[Client and Browser] -->|App credentials and request context| gateway[API7 Gateway 3.10.4]
    gateway -->|Authentication request| identity[Identity Provider]
    identity -->|Verified identity result| gateway
    gateway -->|Gateway-derived identity| api[Upstream API]
    gateway -->|Plugin-owned provider headers| ai[Model Provider]

    control[Control Plane Configuration] --> enabled{SSRF protection enabled?}
    enabled -->|No| outbound[Configured External Endpoint]
    enabled -->|Yes| screen{Destination private or reserved?}
    screen -->|No| outbound
    screen -->|Yes| reject[Refuse connection]

    untrusted[Caller credentials on AI proxy requests] -. not forwarded to model provider .-> gateway

AI Traffic Creates a Multi-Credential Egress Problem

In a conventional API request, the upstream service often needs the credential supplied by the client. In an AI proxy flow, that assumption can be dangerous. The client authenticates to the application or gateway, but the gateway authenticates separately to the model provider. Those credentials have different audiences and should not travel together.

Consider a browser request to an AI assistant. It may include a session Cookie, an Authorization header for the application, tracing headers, and custom tenant metadata. The AI proxy plugin then adds the provider credential required by the configured model service. If the original headers are copied to the provider, a third party receives authentication material and internal context that it does not need.

API7 Gateway 3.10.4 fixes this behavior in AI Proxy, AI Proxy Multi, and AI Request Rewrite. Requests sent to the LLM provider now carry only the headers set by the plugin, rather than inheriting client headers such as Cookie, Authorization, and arbitrary custom fields.

That change establishes an important AI Gateway security boundary:

• The credential used to enter the application stays on the application side.
• The credential used to call the model provider is owned by gateway configuration.
• Custom client context is not exported merely because it was present on the incoming request.
• Provider requests become easier to review because their header set is deliberate rather than inherited.

This is more than credential hygiene. It supports data minimization. Headers can carry tenant IDs, experiment names, internal host information, and correlation values. Even when those fields are not secrets in isolation, exporting them without a defined purpose expands the system's disclosure surface.

Teams upgrading to 3.10.4 should test this as a contract change. If a model-provider integration intentionally depended on a client-supplied custom header, that header will no longer arrive automatically. Move required provider context into supported plugin configuration or an explicitly governed transformation, then verify the exact outbound header set in a non-production environment. Do not restore wholesale header forwarding to preserve an undocumented dependency.

Verified Identity Must Replace Caller-Asserted Identity

Headers such as X-UserId, X-Username, and X-Nickname look authoritative to an upstream service. They are not authoritative when a caller can send them directly.

An authentication plugin should remove identity assertions from the incoming request, establish identity with the configured authentication system, and then add trusted values derived from the result. Version 3.10.4 fixes a wolf-rbac case where the authentication service could return success without userInfo. Previously, the client's own identity headers could then pass through to the upstream. The gateway now always clears those headers before proxying the request.

This follows the same boundary rule as the AI-provider change: a field should not retain a trusted meaning after its source of trust disappears.

OpenID Connect receives complementary improvements. The OpenID Connect plugin can now forward the raw ID token in X-Raw-ID-Token when set_raw_id_token_header is enabled. This gives an upstream the option to verify the identity provider's token signature itself instead of relying only on decoded claims supplied by the gateway.

That capability should be enabled intentionally. A raw ID token is security-sensitive and may contain personal or organizational claims. The upstream needs a reason to receive it, a validation implementation that checks the expected issuer, audience, signature, and time constraints, and logging rules that prevent the token from being recorded. Enabling the option without upstream verification would move the token across another boundary without gaining the intended assurance.

The release also preserves identity data more accurately. Empty arrays returned by the identity provider, such as "roles": [], remain arrays when encoded into X-Userinfo for a request served from an existing session. They no longer become empty objects that can break upstream authorization logic expecting an array. An authorization callback with stale session state now redirects to the originally requested page instead of returning HTTP 500.

Together, these changes separate three concepts that are often blurred:

1. Caller input is untrusted until validated.
2. Gateway-derived identity is trusted according to the configured authentication flow.
3. Identity-provider evidence can be forwarded for independent upstream verification when the risk model requires it.

sequenceDiagram
    participant C as Client
    participant G as API7 Gateway
    participant I as Identity Provider
    participant U as Upstream API

    C->>G: Request plus caller-supplied identity headers
    G->>G: wolf-rbac clears caller-supplied identity headers
    G->>I: Authenticate or validate session
    I-->>G: Verified claims and optional raw ID token
    G->>U: Gateway-derived identity
    opt set_raw_id_token_header enabled
        G->>U: X-Raw-ID-Token for independent verification
    end

Outbound Management Connections Need a Destination Boundary

Gateways are usually discussed as inbound traffic infrastructure, but a Control Plane also makes outbound connections. It can contact service registries, SMTP servers, and other endpoints supplied through configuration. That flexibility creates an SSRF risk when a user who can influence a URL can make the Control Plane connect to a destination they could not reach directly.

Version 3.10.4 adds an opt-in guard controlled by security.ssrf_protection.enable. When enabled, the Control Plane refuses outbound connections to loopback, private, link-local, and carrier-grade NAT addresses, including hostnames that resolve to those ranges. This helps prevent configurable integrations from being used to probe internal services or cloud metadata endpoints.

The setting is opt-in because private destinations are legitimate in many self-hosted deployments. A service registry or SMTP server may intentionally live on an internal address. Enabling SSRF protection without mapping those dependencies could interrupt them; leaving it disabled without analyzing who can configure outbound endpoints preserves a wider trust boundary than some environments intend.

A practical adoption review should therefore answer four questions:

• Which API7 Gateway features initiate outbound Control Plane connections?
• Which destination hostnames and resolved address ranges are expected?
• Who can create or edit the configuration that controls those destinations?
• Which connections should move through an approved proxy or public endpoint before protection is enabled?

SSRF defense also requires DNS-aware testing. A hostname is not safe merely because its text looks public; the guard evaluates addresses it resolves to. Test expected destinations, blocked private ranges, redirects if the integration follows them, and DNS changes during the connection lifecycle.

Network Identity Is Valid Only When the Immediate Peer Is Trusted

At Layer 4, a load balancer can carry the original client address in the PROXY protocol header. The gateway needs that address for stream logs and address-based policy, but it should accept it only from a peer authorized to speak the protocol.

API7 Gateway 3.10.4 adds nginx_config.stream.real_ip_from for TCP and UDP listeners. The setting lists the addresses trusted to supply a PROXY protocol header. When a connection arrives from one of those addresses, the gateway uses the client address from the header instead of the directly connected peer. The list is empty by default and affects only ports configured to accept the PROXY protocol.

This is the stream-traffic equivalent of a trusted-proxy boundary. The value inside the header becomes meaningful because the gateway verified the network source that supplied it—not because the header format was valid.

Before enabling it, operators should map the actual hop immediately in front of each gateway instance. Include load-balancer addresses or CIDR ranges the gateway sees after network address translation, keep the list as narrow as operationally possible, and test both approved and unapproved sources. Then confirm that logs, allowlists, denylists, and rate policies use the expected client address.

Configuration Validation Is Part of the Security Boundary

A secure runtime begins with configuration that has one unambiguous meaning. Version 3.10.4 tightens several validation paths and includes two upgrade notes that deserve attention before rollout.

First, logger fields max_req_body_bytes and max_resp_body_bytes must now be positive integers. Values such as 0, negative numbers, and quoted numbers such as "1024" are rejected. Existing routes with invalid values appear as errors in the gateway group's compatibility report and are not published to the Data Plane, while unaffected routes continue to publish. Teams should replace invalid values with positive integers or remove the field to use the 524,288-byte default.

Second, Prometheus plugin metadata can no longer disable labels that define the structure of a metric, such as type on latency or code on status. Earlier configurations could collapse distinct measurements into one series. After the upgrade, an update containing one of those structural entries in disabled_labels is rejected with HTTP 400. Non-structural labels such as route, service, and consumer can still be disabled.

The release also introduces default 64 MiB request and response buffering limits across plugins that read bodies into memory. An oversized request is rejected. An oversized response is truncated at the limit, except for Proxy Cache, where it passes through without being cached. Logger schemas now expose their body-capture limits consistently as well.

These limits turn an implicit memory assumption into an enforceable boundary. Operators should not automatically raise them to preserve every previous payload. Inventory real payload sizes, identify routes that handle uploads or unusually large AI inputs, and decide whether the affected plugin truly needs the full body. Increasing a limit should come with worker-memory and concurrency analysis.

Control Plane correctness receives similar reinforcement. Concurrent PATCH requests against the same resource are now serialized so both cannot report success while one silently overwrites the other. The merged result of PATCH /apisix/admin/routes is validated against the route schema before storage.

These changes matter because validation and concurrency are trust decisions too. Automation should be able to trust that an accepted update satisfies the schema and that a reported success was not discarded by a simultaneous writer.

What to Review Before Upgrading to 3.10.4

Use the rolling upgrade guide together with the version-specific 3.10.4 release notes. A focused review should include:

1. AI-provider egress: capture the outbound headers for AI Proxy, AI Proxy Multi, and AI Request Rewrite in staging. Move any legitimate provider context into explicit configuration.
2. Identity propagation: on wolf-rbac routes, attempt to spoof X-UserId, X-Username, and X-Nickname; confirm the upstream receives only verified values. If forwarding raw ID tokens, verify signature, issuer, audience, expiry, and log redaction upstream.
3. SSRF exposure: inventory every configurable Control Plane destination and its resolved addresses. Decide whether to enable security.ssrf_protection.enable, redesign private dependencies, or document a compensating control.
4. Stream client addresses: configure nginx_config.stream.real_ip_from only for known PROXY protocol peers and validate behavior from trusted and untrusted sources.
5. Logger compatibility: remove zero, negative, or quoted body-size limits before rollout, then inspect compatibility reports for unpublished routes.
6. Metrics metadata: remove structural Prometheus labels from disabled_labels and confirm dashboards still distinguish status and latency series correctly.
7. Body buffering: test the request-rejection, response-truncation, and Proxy Cache pass-through behavior at configured limits. Recalculate memory headroom before increasing defaults.
8. Concurrent automation: exercise simultaneous PATCH operations and schema rejection in a representative Control Plane environment.

The Apisix-Plugins debug response header can now help during this validation. It lists the plugins that actually ran, in execution order, with the phase for each entry—for example, limit-count#access and response-rewrite#header_filter—instead of returning an unordered list of configured plugins. This makes it easier to compare intended policy with the path a test request actually executed. Restrict debug-header use to appropriate environments and workflows so diagnostic information is not exposed unnecessarily.

Make Context Earn Its Way Across the Gateway

Zero trust is often summarized as “never trust, always verify.” At an API gateway, the practical version is more specific: every piece of context should earn its way across the boundary.

A browser credential should not reach a model provider because the browser supplied it. An identity header should not become authoritative because its name sounds trusted. A raw ID token should not reach an upstream unless the upstream will verify and protect it. A configured URL should not give the Control Plane unrestricted access to internal networks. A PROXY protocol address should not redefine the client unless it came from an approved peer. A configuration update should not be trusted until it is validated and applied consistently.

API7 Gateway 3.10.4 moves these decisions out of hidden inheritance and into explicit behavior. That improves security, but it also improves operability: teams can inspect the rule, test the boundary, and assign an owner when the architecture intentionally makes an exception.

Read the full API7 Gateway 3.10.4 release notes, review each boundary against your traffic and management topology, and canary the upgrade before rolling it across the fleet.