feat: Add guidance on JWKS caching

main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx

@@ -21,6 +21,25 @@ Currently, Auth0 signs with only one JWK at a time; however, it is important to
 
 </Warning>
 
+## Cache the JSON Web Key Set
+
+You should ensure that you cache the JWKS your application retrieves from the JWKS endpoint, as this will:
+
+* Avoid consuming your tenant's [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) with repeated requests.
+* Improve performance by avoiding a network request to the JWKS endpoint on every token validation.
+* Improve resiliency, so your application can continue validating tokens if the JWKS endpoint is briefly unavailable.
+
+Rather than implement caching yourself, we recommend you use a JWKS library or your framework's middleware that caches keys, refetches on an unknown `kid`, and rate-limits those refetches. Our [Quickstarts](/docs/quickstarts) use libraries that handle this for you. If you instead implement this yourself, follow the guidance below.
+
+### Implementation guidance
+
+Cache the JWKS for at least 5-10 minutes to avoid fetching it on every request. Longer intervals further reduce requests and latency.
+
+When you [rotate signing keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys), Auth0 signs new tokens with the new key. If you receive a token whose key ID (`kid`) is not in your cached JWKS, invalidate your cache and fetch the JWKS again to retrieve the new key. This refetch on an unknown `kid` - not the cache lifetime - is what lets your application pick up rotated keys promptly, so a longer cache interval does not delay rotation.
+
+Limit how often you refetch on a cache miss - for example, retry only once - so that a batch of tokens signed with unknown keys cannot trigger a flood of requests to the JWKS endpoint and consume your rate limits. Set your cache interval based on how quickly you need to stop accepting tokens signed with a manually [revoked key](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys).
+
+
 ## Learn more
 
 * [Signing Keys](/docs/get-started/tenant-settings/signing-keys)

main/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets.mdx

@@ -20,7 +20,7 @@ For more info about the structure of a JWT, see [JSON Web Token Structure](/docs
 
 It's good practice to assume that multiple signing keys could be present in your JWKS. This may seem unnecessary since the Auth0 JWKS endpoint typically contains a single signing key; however, multiple keys can be found in the JWKS when rotating signing certificates.
 
-We recommend that you cache your signing keys to improve application performance and avoid running into [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy), but you will want to make sure that if decoding a token fails, you invalidate the cache and retrieve new signing keys before trying **only one** more time.
+We recommend that you cache your signing keys to improve application performance and avoid running into rate limits. To learn how to cache safely and still pick up rotated keys, read [Cache the JSON Web Key Set](/docs/secure/tokens/json-web-tokens/json-web-key-sets#cache-the-json-web-key-set).
 
 ## Learn more
 

main/docs/secure/tokens/token-best-practices.mdx

@@ -96,7 +96,7 @@ The most secure practice, and our recommendation, is to use **RS256** because:
 
 It's good practice to assume that multiple signing keys could be present in your JWKS. This may seem unnecessary since the Auth0 JWKS endpoint typically contains a single signing key; however, multiple keys can be found in the JWKS when rotating signing certificates.
 
-We recommend that you cache your signing keys to improve application performance and avoid running into rate limits, but you will want to make sure that if decoding a token fails, you invalidate the cache and retrieve new signing keys before trying **only one** more time.
+We recommend that you cache your signing keys to improve application performance and avoid running into rate limits. To learn how to cache safely and still pick up rotated keys, read [Cache the JSON Web Key Set](/docs/secure/tokens/json-web-tokens/json-web-key-sets#cache-the-json-web-key-set).
 
 ## Learn more