[TT-17927] Update documentation for master

[probelabs]

User description

Triggered by: jay-deshmukh

Included:

Tyk Gateway: true
Tyk Dashboard: true
Tyk MDCB true
Tyk Pump true
Tyk Portal: true
Tyk Operator CRD: false
Tyk AI Studio: false

Intended for: master
Portal release: master
AI Studio release: main
Pump release: master
MDCB release: master
Changes sourced from: release-5.15
Config info generator branch: main

Note: (branch suffix: docs)

JIRA: https://tyktech.atlassian.net/browse/TT-17927

---

PR Type

Documentation, Enhancement

---

Description

• Add governance, ruleset, and IdP APIs

• Document MCP dryRun and expand flows

• Expand dashboard storage and security config

• Sync gateway, portal, and admin docs

---

Diagram Walkthrough

flowchart LR
  A["Dashboard Swagger"]
  B["Governance and ruleset APIs"]
  C["Client IdP APIs"]
  D["MCP dry-run and expand docs"]
  E["Gateway Swagger"]
  F["Config references"]
  G["Dashboard, Gateway, MDCB, Pump docs"]

  A -- "adds" --> B
  A -- "adds" --> C
  A -- "extends" --> D
  E -- "documents" --> D
  F -- "updates" --> G

Loading

File Walkthrough

Relevant files

Documentation

9 files dashboard-swagger.yml Document governance, client IdP, and MCP APIs                        +2500/-787 x-tyk-gateway.mdx Expand gateway OAS, OAuth2, and MCP docs                                  +528/-131 dashboard-config.mdx Add dashboard storage, Redis, and security settings            +158/-23 gateway-swagger.yml Add MCP dry-run and expand parameters                                        +44/-4    gateway-config.mdx Refresh gateway configuration reference for release sync  +155/-8  mdcb-config.mdx Refresh MDCB configuration reference for release sync        +85/-2    enterprise-developer-portal-swagger.yaml Sync developer portal OpenAPI reference updates                    +33/-4    pump-config.mdx Refresh Pump configuration reference for release sync        +49/-0    dashboard-admin-swagger.yml Sync dashboard admin API reference updates                              +6/-1

---

[probelabs]

This pull request introduces a substantial documentation update to align with a major product release. It documents significant new features across Tyk Gateway, Dashboard, MDCB, and Pump, focusing on enhanced security, configuration management, and advanced API capabilities for AI and enterprise integrations.

Files Changed Analysis

This PR modifies 9 files, with 3,558 additions and 960 deletions. The changes are concentrated in key areas:

• swagger/dashboard-swagger.yml: The largest change (+2500/-787 lines) documents new APIs for governance, rulesets, and client Identity Providers (IdPs).
• snippets/x-tyk-gateway.mdx: Significantly expanded (+528/-131 lines) to detail new OpenAPI-native features, including advanced OAuth2 Token Exchange and the REST-as-MCP (Management Control Plane) proxy for AI use cases.
• Configuration Snippets (*-config.mdx): All major components (Dashboard, Gateway, MDCB, Pump) receive updates documenting new platform-wide configuration options for IAM-based storage authentication and externalized secret management.

Architecture & Impact Assessment

• What this PR accomplishes: It brings the product documentation in sync with a major release, making new enterprise-grade security, integration, and configuration features visible and usable. This reflects a strategic focus on enhanced security, operational maturity, and support for AI/agent-based use cases.

• Key technical changes introduced:

  1. IAM-Based Storage Authentication: A new iam_auth configuration block is documented for Gateway, Dashboard, MDCB, and Pump, allowing these components to authenticate to Redis/Valkey using cloud IAM credentials (initially GCP) instead of static passwords.
  2. External Secret Management (kv): A new kv configuration section is documented across all major components, enabling the resolution of sensitive values (e.g., database credentials) from external stores like HashiCorp Vault or Consul at startup.
  3. REST-as-MCP Proxy Enhancements: The Gateway API now supports dryRun and expand parameters for its MCP endpoints. This allows operators to validate configurations and preview the derived AI tool catalogue from a backend REST API without persisting changes.
  4. Declarative OAuth2 Token Exchange: The Gateway's OpenAPI extension (x-tyk-gateway) is updated to document a declarative, OAS-native implementation of RFC 8693 Token Exchange, allowing complex identity flows to be configured directly within an API definition.
  5. Operational Tuning: New documentation is added for PostgreSQL connection pooling in the Dashboard and for graceful shutdown and regex caching controls in the Gateway.

• Affected system components: Tyk Gateway, Tyk Dashboard, Tyk Multi-Data Centre Bridge (MDCB), Tyk Pump, and the Enterprise Developer Portal.

External Secret Management Flow

graph TD
    subgraph sg1 ["Tyk Component (e.g., Gateway)"]
        direction LR
        ConfigFile[tyk.conf]
        KVResolver(KV Abstraction Layer)
        ConfigFile --|references secret via e.g., vault://...|--> KVResolver
    end

    subgraph sg2 ["External Secret Stores"]
        direction TB
        Vault[HashiCorp Vault]
        Consul[Consul KV]
        Env[Environment Variables]
    end

    KVResolver --|resolves at startup|--> Vault
    KVResolver --|resolves at startup|--> Consul
    KVResolver --|resolves at startup|--> Env

    ResolvedValue((Resolved Secret)) --> ConfigFile

Loading

Scope Discovery & Context Expansion

The changes in this PR document a suite of significant, platform-wide features. The consistent addition of iam_auth and kv configurations across all components indicates a new, shared library for secure configuration management.

The enhancements to the REST-as-MCP proxy, particularly the expand functionality, document a sophisticated new capability within the Gateway to dynamically parse a backend OpenAPI specification and derive a corresponding set of AI tools. This is a foundational feature for enabling advanced AI use cases on the platform.

To fully understand the implementation behind this documentation, a reviewer should investigate:

• The source code for the new configuration structs, such as IAMAuth and kv.Config, in the respective component repositories.
• The Gateway's API handler logic for the MCP dryRun and expand features.
• The middleware implementation for the OAS-native OAuth2 Token Exchange in the Gateway.

Metadata

• Review Effort: 4 / 5
• Primary Label: documentation

---

Powered by Visor from Probelabs

Last updated: 2026-08-27T05:59:06.881Z | Triggered by: pr_updated | Commit: 1eb36b6

💡 TIP: You can chat with Visor using /visor ask <your question>

[probelabs]

Technical-accuracy Issues (4)

Severity	Location	Issue
🟠 Error	swagger/dashboard-swagger.yml:10308-10310	The description for the 403 Forbidden response of the `/governance/evaluate` endpoint states that an error can occur if "a requested api_id is not owned by the caller". This contradicts the parameter description for `api_id` (line 10269), which defines it as a "transient, caller-supplied identifier... does not need to match a stored API." An ownership check is not possible on a transient identifier that doesn't correspond to a stored entity. 💡 Suggestion Clarify the role of `api_id`. If it is truly transient and not used for ownership checks, remove the ownership clause from the 403 response description. If ownership is checked, the parameter description must be updated to reflect that `api_id` must match an existing API under certain conditions.
🟠 Error	swagger/dashboard-swagger.yml:16812	The `categories` field in the `SandboxEvaluationRequest` schema has `maxItems` set to 10, but the description for the `/governance/sandbox` endpoint at line 10355 states that it accepts "one to twenty categories". This inconsistency will cause requests with 11-20 categories to be rejected by clients and validators that adhere to the schema. 💡 Suggestion Update the `maxItems` constraint in the schema to 20 to match the endpoint's description.
🟠 Error	snippets/gateway-config.mdx:2722	The documentation for the new `kv` secret management feature has been added to the configuration files for the Dashboard, MDCB, and Pump, but it is missing from the Gateway's configuration file (`gateway-config.mdx`). The old `kv.KV` section was removed, but it was not replaced with the new standard `kv` documentation block. This omits documentation for a major, platform-wide feature from a key component. 💡 Suggestion Add the standard `kv` configuration documentation block to `snippets/gateway-config.mdx`, consistent with the documentation added to `snippets/dashboard-config.mdx`, `snippets/mdcb-config.mdx`, and `snippets/pump-config.mdx`.
🟡 Warning	swagger/dashboard-swagger.yml:12908	The `GovernanceComplianceData` schema, used within a `oneOf` validator for notification data, does not have any `required` fields. This allows an empty object `{}` to validate against this schema, which can create ambiguity if other schemas in the `oneOf` list can also be satisfied by an empty object. This can break strict OpenAPI validators and code generators. 💡 Suggestion Add `required: [api_id, ruleset_id, status]` to the `GovernanceComplianceData` schema to ensure that it only matches well-formed objects, making the `oneOf` validation deterministic.

Security Issues (3)

Severity	Location	Issue
🔴 Critical	snippets/x-tyk-gateway.mdx:1854-1858	The new `code` field for custom middleware allows for the execution of inline, base64-encoded Javascript directly from an API definition. This feature introduces a critical security risk. If an attacker gains the ability to modify API definitions, they can inject arbitrary code, leading to Remote Code Execution (RCE) on the gateway. The documentation lacks any warning about the severe security implications of enabling and using this feature. 💡 Suggestion Add a prominent security warning to the documentation for the `code` field. The warning should explicitly state that this feature can be used to execute arbitrary code on the gateway and must be treated with extreme caution. It should recommend that access to modify API definitions containing this field be strictly limited to highly privileged and trusted administrators, and that its use should be carefully audited.
🟡 Warning	snippets/dashboard-config.mdx:162-165	The documentation for `storage.main.postgres.max_open_connections` specifies a default value of `0`, which signifies unlimited open connections to the database. This is an insecure default that can lead to resource exhaustion on the database server, creating a Denial of Service (DoS) vulnerability. The same issue is present for the `analytics`, `logs`, and `uptime` storage configurations. 💡 Suggestion Update the documentation to recommend a specific, safe, non-zero default value for `max_open_connections`. Alternatively, add a prominent warning advising administrators to configure a sensible limit based on their database capacity and expected load to mitigate the risk of resource exhaustion.
🟡 Warning	swagger/gateway-swagger.yml:1616-1622	The new `expand=true` query parameter on the MCP proxy endpoint (`POST /tyk/mcp/apis`) can return the full derived tool catalogue and structure of a backend REST API. This functionality could be abused to expose sensitive information about internal API structures, including paths, methods, and parameters. While this is an authenticated admin endpoint, it poses an information disclosure risk if an admin account is compromised or in an insider threat scenario. A similar risk exists for the `GET /tyk/mcp/apis/{apiId}` endpoint and the corresponding `/api/apis/mcp` endpoint in `swagger/dashboard-swagger.yml`. 💡 Suggestion The API documentation for endpoints supporting the `expand=true` parameter should include a security note. This note should warn about the potential for sensitive information disclosure regarding backend service architecture and recommend that access to this functionality be tightly controlled and usage be logged and audited, especially in production environments.

Architecture Issues (1)

Severity	Location	Issue
🟠 Error	snippets/gateway-config.mdx:2716	The new `kv` configuration for external secret management is documented for the Dashboard, MDCB, and Pump, but it is missing from the Gateway configuration. Concurrently, the old `kv.KV` configuration has been removed from the Gateway documentation. This creates a significant inconsistency, leaving the Gateway without a documented method for using the new, standardized external secret management feature that is being rolled out across other components. 💡 Suggestion Add the documentation for the new `kv` configuration block to `snippets/gateway-config.mdx`, consistent with how it has been added for other components like MDCB and Pump. If the feature is not implemented in the Gateway, this represents a major architectural divergence that should be addressed.

Technical-accuracy Issues (4)

Severity	Location	Issue
🟠 Error	swagger/dashboard-swagger.yml:10308-10310	The description for the 403 Forbidden response of the `/governance/evaluate` endpoint states that an error can occur if "a requested api_id is not owned by the caller". This contradicts the parameter description for `api_id` (line 10269), which defines it as a "transient, caller-supplied identifier... does not need to match a stored API." An ownership check is not possible on a transient identifier that doesn't correspond to a stored entity. 💡 Suggestion Clarify the role of `api_id`. If it is truly transient and not used for ownership checks, remove the ownership clause from the 403 response description. If ownership is checked, the parameter description must be updated to reflect that `api_id` must match an existing API under certain conditions.
🟠 Error	swagger/dashboard-swagger.yml:16812	The `categories` field in the `SandboxEvaluationRequest` schema has `maxItems` set to 10, but the description for the `/governance/sandbox` endpoint at line 10355 states that it accepts "one to twenty categories". This inconsistency will cause requests with 11-20 categories to be rejected by clients and validators that adhere to the schema. 💡 Suggestion Update the `maxItems` constraint in the schema to 20 to match the endpoint's description.
🟠 Error	snippets/gateway-config.mdx:2722	The documentation for the new `kv` secret management feature has been added to the configuration files for the Dashboard, MDCB, and Pump, but it is missing from the Gateway's configuration file (`gateway-config.mdx`). The old `kv.KV` section was removed, but it was not replaced with the new standard `kv` documentation block. This omits documentation for a major, platform-wide feature from a key component. 💡 Suggestion Add the standard `kv` configuration documentation block to `snippets/gateway-config.mdx`, consistent with the documentation added to `snippets/dashboard-config.mdx`, `snippets/mdcb-config.mdx`, and `snippets/pump-config.mdx`.
🟡 Warning	swagger/dashboard-swagger.yml:12908	The `GovernanceComplianceData` schema, used within a `oneOf` validator for notification data, does not have any `required` fields. This allows an empty object `{}` to validate against this schema, which can create ambiguity if other schemas in the `oneOf` list can also be satisfied by an empty object. This can break strict OpenAPI validators and code generators. 💡 Suggestion Add `required: [api_id, ruleset_id, status]` to the `GovernanceComplianceData` schema to ensure that it only matches well-formed objects, making the `oneOf` validation deterministic.

\n\n ### Security Issues (3)

Severity	Location	Issue
🔴 Critical	snippets/x-tyk-gateway.mdx:1854-1858	The new `code` field for custom middleware allows for the execution of inline, base64-encoded Javascript directly from an API definition. This feature introduces a critical security risk. If an attacker gains the ability to modify API definitions, they can inject arbitrary code, leading to Remote Code Execution (RCE) on the gateway. The documentation lacks any warning about the severe security implications of enabling and using this feature. 💡 Suggestion Add a prominent security warning to the documentation for the `code` field. The warning should explicitly state that this feature can be used to execute arbitrary code on the gateway and must be treated with extreme caution. It should recommend that access to modify API definitions containing this field be strictly limited to highly privileged and trusted administrators, and that its use should be carefully audited.
🟡 Warning	snippets/dashboard-config.mdx:162-165	The documentation for `storage.main.postgres.max_open_connections` specifies a default value of `0`, which signifies unlimited open connections to the database. This is an insecure default that can lead to resource exhaustion on the database server, creating a Denial of Service (DoS) vulnerability. The same issue is present for the `analytics`, `logs`, and `uptime` storage configurations. 💡 Suggestion Update the documentation to recommend a specific, safe, non-zero default value for `max_open_connections`. Alternatively, add a prominent warning advising administrators to configure a sensible limit based on their database capacity and expected load to mitigate the risk of resource exhaustion.
🟡 Warning	swagger/gateway-swagger.yml:1616-1622	The new `expand=true` query parameter on the MCP proxy endpoint (`POST /tyk/mcp/apis`) can return the full derived tool catalogue and structure of a backend REST API. This functionality could be abused to expose sensitive information about internal API structures, including paths, methods, and parameters. While this is an authenticated admin endpoint, it poses an information disclosure risk if an admin account is compromised or in an insider threat scenario. A similar risk exists for the `GET /tyk/mcp/apis/{apiId}` endpoint and the corresponding `/api/apis/mcp` endpoint in `swagger/dashboard-swagger.yml`. 💡 Suggestion The API documentation for endpoints supporting the `expand=true` parameter should include a security note. This note should warn about the potential for sensitive information disclosure regarding backend service architecture and recommend that access to this functionality be tightly controlled and usage be logged and audited, especially in production environments.

\n\n ### Architecture Issues (1)

Severity	Location	Issue
🟠 Error	snippets/gateway-config.mdx:2716	The new `kv` configuration for external secret management is documented for the Dashboard, MDCB, and Pump, but it is missing from the Gateway configuration. Concurrently, the old `kv.KV` configuration has been removed from the Gateway documentation. This creates a significant inconsistency, leaving the Gateway without a documented method for using the new, standardized external secret management feature that is being rolled out across other components. 💡 Suggestion Add the documentation for the new `kv` configuration block to `snippets/gateway-config.mdx`, consistent with how it has been added for other components like MDCB and Pump. If the feature is not implemented in the Gateway, this represents a major architectural divergence that should be addressed.

\n\n ### Performance Issues (2)

Severity	Location	Issue
🟡 Warning	snippets/dashboard-config.mdx:164-168	The default value of 0 (unlimited) for `max_open_connections` can lead to database connection exhaustion under load. This setting is documented for `storage.main`, `storage.analytics`, `storage.logs`, and `storage.uptime`. In a production environment with multiple Tyk Dashboard replicas, an unlimited number of connections can overwhelm the PostgreSQL server, causing severe performance degradation. The documentation should warn users about this risk. 💡 Suggestion For each `max_open_connections` field, add a recommendation to set a specific limit for production deployments. For example: 'For production environments, it is strongly recommended to set a limit based on your database capacity and number of Dashboard replicas to prevent connection exhaustion.'
🟡 Warning	snippets/dashboard-config.mdx:176-180	The default behavior of reusing connections forever (`connection_max_lifetime` is empty) can cause intermittent request failures in environments with stateful firewalls or load balancers that close idle connections. This applies to all four PostgreSQL storage configurations (`main`, `analytics`, `logs`, `uptime`). This can lead to poor performance and errors when the Dashboard attempts to use a connection that has been silently terminated by a network device. 💡 Suggestion For each `connection_max_lifetime` field, add a note advising users to set a lifetime shorter than any network infrastructure timeouts. For example: 'It is recommended to set this to a value like `30m` to prevent errors caused by network devices closing idle connections.'

---

Powered by Visor from Probelabs

Last updated: 2026-08-27T05:58:35.173Z | Triggered by: pr_updated | Commit: 1eb36b6

💡 TIP: You can chat with Visor using /visor ask <your question>

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Schema mismatch The sandbox evaluation docs describe a 20-category input cap, but the published schema only allows 10 categories. OpenAPI-based validators and generated clients will reject requests with 11-20 categories even though the endpoint description says those requests are supported. categories: type: array minItems: 1 maxItems: 10 items: {type: string} Conflicting auth docs This endpoint documents api_id as a transient caller-supplied identifier used only for echoing results, but the 403 response says ownership is checked against a requested api_id. Those two behaviors conflict. A CI caller using a synthetic api_id would be told to expect an ownership failure for an identifier that is not supposed to map to a stored API. "403": description: Forbidden — governance is disabled at deployment level (license / config feature flag), the user lacks the APIs permission, or (with API ownership enabled) a requested api_id is not owned by the caller. Sandbox evaluations are read-only previews, so `apis:read` is sufficient; `apis:deny` or a permissions map without an `apis` entry is rejected. content: application/json: schema: {$ref: '#/components/schemas/ApiResponse'} "404": description: Any explicit `ruleset_ids` entry not found within the org or soft-deleted.

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Require notification payload fields Make GovernanceComplianceData require its identifying fields so Notification.data.oneOf can be validated deterministically. As written, an empty or malformed object can also satisfy this branch, which makes the new oneOf ambiguous and breaks strict OpenAPI validators and generated clients. swagger/dashboard-swagger.yml [12908-12918] GovernanceComplianceData: + required: + - api_id + - ruleset_id + - status properties: api_id: type: string ruleset_id: type: string status: type: string enum: [ "failure" ] type: object x-go-package: github.com/TykTechnologies/tyk-analytics/dashboard/repository/notification Suggestion importance[1-10]: 7 __ Why: GovernanceComplianceData currently has no required fields, so it can accept overly broad objects inside Notification.data.oneOf. Adding required for api_id, ruleset_id, and status improves OpenAPI validation and generated-client behavior, but it is a schema-quality issue rather than a critical runtime bug.	Medium

[sharadregoti]

Suggested change

	version: 5.14.0
	version: 5.15.0

[sharadregoti]

Suggested change

	version: 5.14.0
	version: 5.15.0

[sharadregoti]

Suggested change

	version: 5.14.0
	version: 5.15.0

[sharadregoti]

Please add this back.

[sharadregoti]

Why are we removing this?

[sharadregoti]

Suggested change

	Enables [API Ownership](/tyk-dashboard/rbac#enabling-api-ownership) in MDCB. If set, the Data Plane Gateways will load only APIs that are accessible by the user and user group associated with the Gateways' [slave_options.api_key](/tyk-oss-gateway/configuration#slave_options-api_key) used to connect to MDCB.
	Enables [API Ownership](/platform-management/api-ownership) in MDCB. If set, the Data Plane Gateways will load only APIs that are accessible by the user and user group associated with the Gateways' [slave_options.api_key](/tyk-oss-gateway/configuration#slave_options-api_key) used to connect to MDCB.