From 4f8a9fa38e1f4b9c1deca38be5a18f38ba06347f Mon Sep 17 00:00:00 2001 From: acomarcho Date: Tue, 14 Oct 2025 20:32:55 +0700 Subject: [PATCH] chore(docs): update documentations on leeway --- docs/usage.rst | 17 +++++++++++++++++ jwt/api_jwt.py | 4 ++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index c50b70a8..3615951b 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -352,6 +352,23 @@ Issued At Claim (iat) >>> token = jwt.encode({"iat": 1371720939}, "secret") >>> token = jwt.encode({"iat": datetime.datetime.now(tz=timezone.utc)}, "secret") +The `iat` claim also supports the leeway feature similar to the `exp` and `nbf` claims. +This allows you to validate an "issued at" time that is slightly in the future. Using +leeway with the iat claim can be particularly helpful in scenarios where clock +synchronization between the token issuer and the validator is imprecise. + +.. code-block:: pycon + + >>> import time, datetime + >>> from datetime import timezone + >>> payload = { + ... "iat": datetime.datetime.now(tz=timezone.utc) + datetime.timedelta(seconds=3) + ... } + >>> token = jwt.encode(payload, "secret") + >>> # JWT was issued in the future (due to clock skew) + >>> # But with some leeway, it will still validate + >>> decoded = jwt.decode(token, "secret", leeway=5, algorithms=["HS256"]) + Subject Claim (sub) ~~~~~~~~~~~~~~~~~~~ diff --git a/jwt/api_jwt.py b/jwt/api_jwt.py index 5bb53ee5..e1dc3753 100644 --- a/jwt/api_jwt.py +++ b/jwt/api_jwt.py @@ -211,7 +211,7 @@ def decode_complete( :type audience: str or typing.Iterable[str] or None :param issuer: optional, the value for ``verify_iss`` check :type issuer: str or typing.Container[str] or None - :param leeway: a time margin in seconds for the expiration check + :param leeway: a time margin in seconds for time-based claims (exp, nbf, iat) to account for clock skew :type leeway: float or datetime.timedelta :rtype: dict[str, typing.Any] :returns: Decoded JWT with the JOSE Header on the key ``header``, the JWS @@ -335,7 +335,7 @@ def decode( :type subject: str or None :param issuer: optional, the value for ``verify_iss`` check :type issuer: str or typing.Container[str] or None - :param leeway: a time margin in seconds for the expiration check + :param leeway: a time margin in seconds for time-based claims (exp, nbf, iat) to account for clock skew :type leeway: float or datetime.timedelta :rtype: dict[str, typing.Any] :returns: the JWT claims