add documentation for JWT caching (#683)

docs/references/auth.rst

@@ -114,6 +114,15 @@ To make an authenticated request the client must include an :code:`Authorization
 
 The ``Bearer`` header value can be used with or without capitalization(``bearer``).
 
+.. _jwt_caching:
+
+JWT Caching
+-----------
+
+PostgREST validates ``JWTs`` on every request. We can cache ``JWTs`` to avoid this performance overhead.
+
+To enable JWT caching, the config :code:`jwt-cache-max-lifetime` is to be set. It is the maximum number of seconds for which the cache stores the JWT validation results. The cache uses the :code:`exp` claim to set the cache entry lifetime. If the JWT does not have an :code:`exp` claim, it uses the config value. See :ref:`jwt-cache-max-lifetime` for more details.
+
 Symmetric Keys
 ~~~~~~~~~~~~~~
 

docs/references/configuration.rst

@@ -628,6 +628,21 @@ jwt-secret-is-base64
 
   When this is set to :code:`true`, the value derived from :code:`jwt-secret` will be treated as a base64 encoded secret.
 
+.. _jwt-cache-max-lifetime:
+
+jwt-cache-max-lifetime
+----------------------
+
+  =============== =================================
+  **Type**        Int
+  **Default**     0
+  **Reloadable**  Y
+  **Environment** PGRST_JWT_CACHE_MAX_LIFETIME
+  **In-Database** `n/a`
+  =============== =================================
+
+  Maximum number of seconds of lifetime for cached entries. The default :code:`0` disables caching. See :ref:`jwt_caching`.
+
 .. _log-level:
 
 log-level