API7 Gateway 3.9.15

This release adds new plugin configuration fields: log_format_extra on the logger plugins and Redis session storage (session.storage and session.redis) for openid-connect.

Release Date: 2026-06-22

Upgrade Notes

Upgrade note — new plugin fields require both Control Plane and Data Plane on 3.9.15

This release adds new plugin configuration fields: log_format_extra on the logger plugins and Redis session storage (session.storage and session.redis) for openid-connect. Because API7 EE upgrades the Control Plane before the Data Plane, a 3.9.15 Control Plane accepts these fields while an older Data Plane does not yet implement them. Configure these new options only after both the Control Plane and the Data Plane are upgraded to 3.9.15.

Upgrade note — SSO-only domains can no longer use local sign-in

In the Developer Portal, the SSO-only domain policy is now enforced on the server, not only in the browser. Local sign-in and sign-up methods — email and password sign-in and sign-up, magic link, and password reset — are now rejected for email addresses whose domain is mapped to an SSO-only provider. Previously these endpoints could be called directly, bypassing the SSO requirement. If users on SSO-managed domains relied on local sign-in, ensure they sign in through SSO after upgrading.

Upgrade note — Developer Portal API proxy is now default-deny

The Developer Portal's API proxy no longer forwards arbitrary backend endpoints. Only an explicit allowlist of organization-scoped resources (API products, applications, credentials, subscriptions, and DCR providers) is proxied; any other path now returns HTTP 404. Read-only resources reject write methods with HTTP 405, writes to applications, credentials, and subscriptions require an owner or admin role (HTTP 403 otherwise), and organization-scoped requests require an authenticated session (HTTP 401 otherwise). If you have integrations that reached other endpoints through the portal proxy, update them to use a supported API path or call the Control Plane directly.

Upgrade note — Developer Portal sign-up consent configuration changed

The Developer Portal sign-up consent options tosURL and beforeSignUpButtonHtml have been replaced by a single signUpConsentLabel, which holds the custom HTML shown next to the consent checkbox. Terms-of-Service acceptance is now enforced only when signUpConsentLabel is configured. If your deployment set tosURL or beforeSignUpButtonHtml, migrate the value to signUpConsentLabel before upgrading.

Features

Plugins

OpenID Connect (opens in Plugin Hub docs)
- Added Redis as a session storage backend. Set session.storage to redis (the default remains cookie) and configure the connection under session.redis (host, port, authentication, database, key prefix, TLS, and timeouts). Storing sessions in Redis lets multiple gateway nodes and routes share a session and refresh tokens centrally. The Redis password is encrypted at rest, and existing cookie-based configurations are unaffected.

Data Plane

The logger plugins now accept a log_format_extra option that adds fields on top of the default log entry instead of replacing it. Previously, setting log_format replaced the entire default entry and dropped fields that have no scalar variable (such as header maps, the parsed query string, the composed URL, and computed latencies); log_format_extra keeps the full default entry and overlays your additional fields. When log_format is set, it still takes precedence and log_format_extra is ignored. A new $upstream_unresolved_host variable is also available, recording the configured upstream host or domain before DNS resolution.
The PROXY protocol for stream (TCP) proxying can now be enabled per listening port. Each stream_proxy.tcp entry accepts two optional fields — proxy_protocol (accept the PROXY protocol on that port) and proxy_protocol_to_upstream (send it to the upstream) — which override the global proxy_protocol.enable_tcp_pp and enable_tcp_pp_to_upstream defaults. Ports without these fields keep the global behavior, so existing configurations are unchanged.
Debug sessions now capture each sampled request's log lines (all levels) and attach them to that request's trace as span events. The per-request logs appear alongside the trace in the debug session view, making it easier to correlate log output with a specific traced request.

Developer Portal

The Developer Portal can now run inside a custom PostgreSQL schema instead of only the default public schema. The schema is set in the portal configuration (kept out of the connection URL); the portal applies it per connection and runs its migrations within that schema.

Fixes

Plugins

JWT Auth (opens in Plugin Hub docs)
- Fixed issue: A token whose signature was malformed (wrong length or not valid base64url) caused the verifier to raise an error and return HTTP 500 instead of rejecting the request. Malformed signatures are now rejected with HTTP 401.
AI Proxy (opens in Plugin Hub docs) and AI Proxy Multi (opens in Plugin Hub docs)
- Fixed issue: When an upstream LLM provider returned an HTTP 429 or 5xx response, the gateway returned only the status code with an empty body, discarding the provider's error details (such as rate-limit information). The upstream error response body and its Content-Type are now forwarded to the client when the request is not retried.
Loki Logger (opens in Plugin Hub docs)
- Fixed issue: When label values referenced per-request variables (for example $service_name or $host), the value resolved for one request was reused for the other requests in the same batch and could remain frozen across requests, so logs were sent under the wrong labels. Labels are now resolved per request, and each request's logs are grouped into their own Loki stream under its own label set.
HMAC Auth (opens in Plugin Hub docs)
- Fixed issue: With validate_request_body enabled, the request body the plugin buffers to verify the signature was limited to 512 KiB by default, rejecting larger bodies that the upstream would accept, and an over-limit body was reported as a misleading HTTP 401. The default max_req_body_size is now 64 MiB (aligned with APISIX), and a body that exceeds the limit is rejected with HTTP 413.

Data Plane

Fixed issue: With consistent-hashing (chash) load balancing, the hash ring was rebuilt from only the currently healthy nodes whenever a node's health changed, which — especially with uneven node weights — reshuffled the ring and moved keys that were already mapped to healthy nodes. The ring is now rebuilt only on configuration or weight changes, and node health is evaluated at selection time, so transient health changes no longer disrupt the sticky routing of unaffected keys. This applies to both upstream chash and ai-proxy-multi chash balancing.

Control Plane

Fixed issue: A Data Plane already running the exact version the Control Plane expects could still be shown as Upgrade Required in the Dashboard when it reported invalid plugin or configuration fields, even though no newer version was available to upgrade to. A Data Plane on the expected version is now kept compatible; the reported configuration problems are still surfaced separately as configuration error and warning indicators.

Developer Portal

Fixed issue: Several two-factor authentication errors were not surfaced — enabling or disabling 2FA with an incorrect password appeared to succeed, the backup-codes dialog could appear empty, and entering a wrong TOTP code at sign-in silently proceeded into the portal. Incorrect passwords and TOTP codes are now correctly rejected with a clear error.