[TT-15683] Added docs for Dashboard API JWKS cache flush endpoint

[andyo-tyk]

PR Type

Documentation

---

Description

• Document JWKS cache management endpoints

• Add Dashboard API endpoint details

• Update auth headers in examples

• Clarify version availability and permissions

---

Diagram Walkthrough

flowchart LR
  GW["Gateway API endpoints (/tyk/cache/jwks)"]
  DB["Dashboard API endpoint (/api/cache/jwks/{apiID})"]
  ALL["Flush all JWKS caches"]
  ONE["Flush JWKS cache for API"]
  MULTI["Flush across all connected Gateways"]

  GW -- "DELETE /tyk/cache/jwks" --> ALL
  GW -- "DELETE /tyk/cache/jwks/{apiID}" --> ONE
  DB -- "DELETE /api/cache/jwks/{apiID}" --> MULTI

Loading

File Walkthrough

	Relevant files
Documentation	jwt-signature-validation.mdx Document Dashboard JWKS cache flush and update examples    api-management/authentication/jwt-signature-validation.mdx Generalize section to Gateway and Dashboard. Add Dashboard endpoint with version and scope. Clarify permissions and org scope requirements. Update curl examples and headers. +13/-8

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Accuracy Verify version availability and permissions: confirm that the Dashboard endpoint /api/cache/jwks/{apiID} is indeed available from Tyk 5.11.0+, and that it requires admin privileges and is scoped to the user's Organisation as stated. | Endpoint | Method | Description | Availability | | ------------------------- | -------- | ---------------------------------------- | ------------ | | `/tyk/cache/jwks` | `DELETE` | Invalidate JWKS caches for all APIs | Tyk 5.10.0+ | | `/tyk/cache/jwks/{apiID}` | `DELETE` | Invalidate JWKS cache for a specific API | Tyk 5.10.0+ | | `/api/cache/jwks/{apiID}` | `DELETE` | Invalidate JWKS cache for a specific API on all connected Gateways | Tyk 5.11.0+ | Note: The Dashboard API endpoint is restricted to users with `admin` privileges and can only be used to flush the cache for APIs in the user's [Organisation](/tyk-dashboard-api#organisations%2C-apis-and-users). **Example usage:** Consistency Ensure header names and secrets are correct and consistent with other docs: x-tyk-authorization for Gateway and authorization for Dashboard; confirm port and path correctness for Dashboard examples. # Flush all JWKS caches curl -X DELETE http://your-gateway:8080/tyk/cache/jwks \ -H "x-tyk-authorization: your-gateway-secret" # Flush JWKS cache for specific API curl -X DELETE http://your-gateway:8080/tyk/cache/jwks/your-api-id \ -H "x-tyk-authorization: your-gateway-secret" # Flush JWKS cache for specific API on all connected Gateways curl -X DELETE http://your-dashboard:8080/api/cache/jwks/your-api-id \ -H "authorization: your-dashboard-secret" </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/1021/files#diff-77577e119313c14102d1038c68e0775d4801d021a2c11d3a5db19155ccdafa07R231-R238'><strong>Clarity</strong></a> Consider clarifying that `/api/cache/jwks/{apiID}` flushes across all connected Gateways of the Dashboard's control plane, and whether Classic vs OAS behavior differences apply equally. </summary> ```txt Tyk Gateway and Dashboard APIs expose endpoints to manage JWKS caches programmatically for both Tyk OAS and Tyk Classic APIs: | Endpoint | Method | Description | Availability | | ------------------------- | -------- | ---------------------------------------- | ------------ | | `/tyk/cache/jwks` | `DELETE` | Invalidate JWKS caches for all APIs | Tyk 5.10.0+ | | `/tyk/cache/jwks/{apiID}` | `DELETE` | Invalidate JWKS cache for a specific API | Tyk 5.10.0+ | | `/api/cache/jwks/{apiID}` | `DELETE` | Invalidate JWKS cache for a specific API on all connected Gateways | Tyk 5.11.0+ |

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Security	Use bearer auth in example Use a bearer token scheme example to avoid implying that raw secrets are passed in the header, which can be insecure and inconsistent with typical Dashboard auth. api-management/authentication/jwt-signature-validation.mdx [252-253] # Flush JWKS cache for specific API on all connected Gateways curl -X DELETE http://your-dashboard:8080/api/cache/jwks/your-api-id \ - -H "authorization: your-dashboard-secret" + -H "Authorization: Bearer your-dashboard-token" Suggestion importance[1-10]: 7 __ Why: Replacing a raw secret header with a bearer token example improves security posture and consistency with common auth patterns, with clear, accurate changes to the example.	Medium
General	Clarify endpoint propagation scope Explicitly state that this Dashboard endpoint targets Gateways connected to the same Dashboard and that offline Gateways will flush on next sync to prevent operational misunderstandings. api-management/authentication/jwt-signature-validation.mdx [237] -| `/api/cache/jwks/{apiID}` | `DELETE` | Invalidate JWKS cache for a specific API on all connected Gateways | Tyk 5.11.0+ | +| `/api/cache/jwks/{apiID}` | `DELETE` | Invalidate JWKS cache for a specific API on all Gateways connected to this Dashboard (offline nodes apply on next sync) | Tyk 5.11.0+ | Suggestion importance[1-10]: 6 __ Why: Adds useful operational clarity about scope and offline nodes for the new Dashboard endpoint, aligning with the description of “all connected Gateways.” It’s plausible and helpful, though not strictly required.	Low
	Clarify scope and fix anchor Clarify whether the action is audited and if org scoping applies when multiple orgs share a Dashboard. Also, standardize the spelling to "Organization" to match product/docs consistency and avoid broken anchors. api-management/authentication/jwt-signature-validation.mdx [239] -Note: The Dashboard API endpoint is restricted to users with `admin` privileges and can only be used to flush the cache for APIs in the user's [Organisation](/tyk-dashboard-api#organisations%2C-apis-and-users). +Note: The Dashboard API endpoint is restricted to users with `admin` privileges and can only be used to flush the cache for APIs in the user's Organization. Actions are scoped to the requesting user's Organization and are audit-logged where enabled. See [Organizations, APIs, and Users](/tyk-dashboard-api#organizations-apis-and-users) for details. Suggestion importance[1-10]: 4 __ Why: The clarification and anchor/spelling normalization may improve accuracy and navigation, but they introduce assumptions (auditing behavior) not evidenced in the PR. Impact is moderate and content-focused, not fixing a bug.	Low