API7 Gateway 3.9.8

Release Date: 2026-04-07

Breaking Changes

Plugins

• Limit Count

  Upgrade note

  The sync_interval (Redis delayed sync) feature has been removed from the limit-count plugin and is now available exclusively in the Limit Count Advanced (opens in Plugin Hub docs) plugin. If you are using limit-count with sync_interval configured, migrate your configuration to the limit-count-advanced plugin before upgrading.

• OpenID Connect (opens in Plugin Hub docs)

  Upgrade note

  The default value of ssl_verify has been changed from false to true. If you have OpenID Connect plugin configurations that do not explicitly set ssl_verify and your identity provider uses a self-signed certificate or a certificate issued by an internal CA, TLS verification will now fail after upgrading. Explicitly set ssl_verify to false in affected configurations before upgrading, or ensure the IdP certificate is trusted by the gateway's CA store.

Features

Plugins

• MCP Tools ACL (opens in Plugin Hub docs) (New Plugin)
  • Added a new plugin for per-tool access control on MCP services exposed via the OpenAPI-to-MCP plugin. Supports allowlist (allow_tools) and denylist (deny_tools) modes with expression-based matching conditions for route-level or service-level tool access policies. Consumers and consumer groups are supported with priority-based rule evaluation. SSE responses are automatically filtered to remove denied tools from tools/list results.
• AI Proxy (opens in Plugin Hub docs), AI Proxy Multi (opens in Plugin Hub docs)
  • Added native Anthropic Messages API support. Requests to /v1/messages using the Anthropic SDK format are now passed through directly to Anthropic-compatible backends without protocol conversion, preserving Anthropic-specific fields such as cache token usage.
  • Added full support for the OpenAI Responses API (POST /v1/responses). Both streaming and non-streaming responses are handled, and all downstream plugins (RAG, content moderation, prompt decorator, prompt guard, logging) work correctly with the Responses API format. Both plugins share the same AI protocol handling, so this also applies to ai-proxy-multi routes.
• AI Rate Limiting (opens in Plugin Hub docs)
  • Added a new expression limit strategy with the cost_expr field, allowing dynamic token cost calculation using custom Lua arithmetic expressions. For example, input_tokens + cache_creation_input_tokens enables cache-aware input token per minute (ITPM) rate limiting for Anthropic Claude.
• OAS Validator (opens in Plugin Hub docs)
  • Added support for OpenAPI 3.1 specification validation, including features such as exclusiveMinimum/exclusiveMaximum as numbers, if/then/else conditional schemas, nullable types via ["string", "null"], const, patternProperties, prefixItems, and JSON Schema $dynamicRef/$dynamicAnchor.
  • Added a configurable rejection_status_code option (400–599, default 400). This allows distinguishing semantic validation errors (e.g., 422 Unprocessable Entity) from malformed request syntax (400 Bad Request).
• Request ID (opens in Plugin Hub docs)
  • Added uuidv7 as a new algorithm option. UUID v7 generates time-ordered, lexicographically sortable unique identifiers, making them more suitable for distributed tracing and log correlation than random UUID v4.
• OpenAPI to MCP (opens in Plugin Hub docs)
  • Added support for OpenAPI in: header parameters. Header parameters defined in OpenAPI specs are now correctly included in MCP tool schemas and forwarded as HTTP headers when invoking the upstream API.

Control Plane

• Added support for Vault dynamic roles for database credential rotation. Dynamic roles create temporary database users with a configurable lease TTL, improving security compared to static roles. Dynamic role is now the default mode, with automatic startup retry using exponential backoff.
• Added a standalone file-server component for hosting files accessible by MCP servers. Files can be uploaded via the Dashboard API and served through a dedicated port. The file server is disabled by default and can be enabled in the system settings.
• Added HTTP Bridge as a new Dynamic Client Registration (DCR) provider type. HTTP Bridge proxies DCR operations (register, update, delete, rotate secret) to an external identity provider via configurable HTTP endpoints.
• Added Data Plane compatibility reporting. When Control Plane and Data Plane versions differ, the Data Plane now reports incompatible resource details (schema validation failures, unknown plugin fields, missing plugins) via heartbeat. Compatibility status is viewable through the runtime instance API.
• Services can now be published without upstream configuration, enabling AI Proxy and other plugin-only scenarios where no backend upstream is needed.
• Optimized custom plugin synchronization with incremental cache refresh. The periodic sync job now queries only for changes instead of performing a full table scan, significantly reducing database load.

Data Plane

• Improved Redis Sentinel connection performance. Master node addresses are now cached with a configurable TTL, reducing Sentinel round-trip queries on each new connection. Additionally, pooled connections skip redundant AUTH and SELECT DB commands, lowering latency for high-throughput Redis operations.

Developer Portal

• Added admin impersonation. Portal administrators can impersonate organization owners to troubleshoot issues, with a 1-hour time-to-live and a persistent warning banner during impersonation.
• Added OAuth client secret regeneration for HTTP Bridge credentials. Organization owners can regenerate secrets through a confirmation modal in the credential management UI.
• Added configurable TOTP-based two-factor authentication (2FA) for Developer Portal login.
• Added role-based access control (RBAC) with three roles: Owner (full control, including organization deletion), Admin (all permissions except organization deletion), and Member (view-only access).
• Organization settings now use slug-prefixed URLs. Page URLs update automatically when switching organizations or renaming the organization slug.
• Application detail pages now display configuration based on portal settings.
• Added an optional signup notice HTML slot for displaying trusted custom content before the sign-up button on the authentication page.

Fixes

Plugins

• AI Aliyun Content Moderation (opens in Plugin Hub docs)
  • Fixed issue: Empty or whitespace-only content caused a 400 error from the Alibaba Cloud moderation API. Additionally, LLM error responses (status ≥ 400) triggered a 500 error during response moderation, and multimodal content arrays crashed text extraction.
• AI Proxy (opens in Plugin Hub docs)
  • Fixed issue: The apisix_llm_active_connections Prometheus gauge was never decremented when a plugin exited early via ngx.exit(), causing the metric to grow indefinitely and report incorrect active connection counts.
• AI Rate Limiting (opens in Plugin Hub docs), Limit Conn (opens in Plugin Hub docs), Limit Req (opens in Plugin Hub docs)
  • Fixed issue: $env:// and $secret:// references in Redis host configuration were passed as literal strings instead of being resolved to their actual values, causing Redis connection failures.
• Fixed issue: API keys, authentication tokens, OAuth credentials, and full plugin configuration payloads were logged in plaintext across multiple plugin and agent log outputs. Sensitive data is now redacted.

Control Plane

• Fixed issue: Updating service runtime configuration (e.g., toggling service status) via PATCH failed with a schema validation error when the service had no upstream configured.
• Fixed issue: HTTP and stream subsystem plugins sharing the same name used a single cache entry, causing the wrong plugin schema to be used for validation when both subsystems were active.
• Fixed issue: Subscriptions could be deleted across API products without validating that the subscription belonged to the target product.
• Fixed issue: Services without upstream configuration showed phantom empty upstream records in the upstream list API.
• Fixed issue: Control Plane crashed with a nil pointer dereference during upgrade migration when processing services with no upstream configured.
• Fixed issue: Multiple API Products within the same Developer Portal could link to the same gateway service (same service ID and gateway group), causing configuration conflicts.
• Fixed issue: Updating an SSL certificate allowed SNI collisions when adding new domains that conflicted with existing certificates.
• Fixed issue: Deleting an API Product that shared a gateway service with another product incorrectly removed all system plugins from the shared service, breaking the other product's authentication configuration.
• Fixed issue: DCR provider authentication headers (such as Bearer tokens) were stored in the database without encryption.
• Fixed issue: Consumer credential secrets were not masked in audit logs due to a value/pointer receiver mismatch.
• Fixed issue: Approval handlers (accept/reject subscription) continued execution after returning a 403 status, bypassing the permission check and processing the request.
• Fixed issue: Read-only Developer Portal users could cancel API Product subscriptions because the endpoint used a read permission check instead of write.
• Fixed issue: PATCH operations on route and stream route runtime configurations used read-only or view-only permission checks, allowing users without write access to modify configurations.
• Fixed issue: Upstream resources were not validated against the requested service, allowing access to upstreams belonging to other services.
• Fixed issue: The CAS SSLVerify configuration flag was inverted, causing TLS certificate verification to be disabled when it was configured as enabled. This could expose CAS authentication connections to man-in-the-middle attacks.
• Fixed issue: Concurrent requests from ADC caused a fatal crash (concurrent map writes) in the route validator due to unsynchronized access to lazy-initialized schema cache maps.
• Fixed issue: API call statistics flush held a database lock during IO operations, causing performance degradation under high traffic. The flush mechanism now uses swap-and-release with batch writes.

Console (Dashboard)

• Fixed issue: The Service Hub page and related modals crashed when a service had an empty or missing name.
• Fixed issue: Adding the same service published to different gateway groups as linked services, was incorrectly blocked by frontend validation.

Data Plane

• Fixed issue: DNS resolution intermittently returned incorrect IP addresses. When the gateway operated in cache-only mode, DNS Additional section records (nameserver glue records) were incorrectly included in resolution results and their domain names overwritten with the queried domain. This caused random upstream connection failures, as the gateway occasionally selected a nameserver IP instead of the actual service IP.
• Fixed issue: Stream routes with service_id silently failed if the referenced service arrived after the route via etcd sync. Service status changes (enable/disable) and deletions also did not trigger stream router rebuild.

Developer Portal

• Fixed issue: Every unauthenticated request to the Developer Portal generated a "No developer ID in session" log entry, flooding production logs and obscuring real errors.
• Fixed issue: The "Regenerate Secret" option was shown (as disabled) for OIDC provider credentials, instead of being hidden. It is now only visible for HTTP Bridge credentials.
• Fixed issue: After re-signing in without logging out, the owner role was not properly restored, causing role-gated UI buttons to appear disabled until a manual page refresh.