chore(docs): update documentations on leeway

[acomarcho]

Hi, first of all, thank you for the great library!

I made this PR as I was having some troubles navigating around the documentation. For the context:

1. I am using this library in a project I'm working at right now.
2. I was having some problems with clock drifts, some of my clients were sending in iat that are faster than my server time.
3. I wanted to fix this by using the leeway property, but got confused as in "does this library support it or not?"
4. Documentations for leeway only exists for nbf and exp, so I was thinking "oh, then, leeway doesn't work for iat"
5. I cloned the codebase to take a look at myself and found out that in the function _validate_iat actually does! (see appendix A)
6. I figured out, "it probably would be helpful if the documentation states this."
7. Then I also realized that in the API docs it's stating that leeway is only for expiration which might be misleading.

See appendix B for the screenshots of the updated documentation.

Apologies for any mistakes if I'm contributing the wrong way (do I need to create an issue first, etc.) - this is my first time contributing to one. This PR was mostly inspired by #1034 which adds documentation for nbf.

Appendix A

    def _validate_iat(
        self,
        payload: dict[str, Any],
        now: float,
        leeway: float,
    ) -> None:
        try:
            iat = int(payload["iat"])
        except ValueError:
            raise InvalidIssuedAtError(
                "Issued At claim (iat) must be an integer."
            ) from None
        if iat > (now + leeway): # <-- leeway validation is done for iat too!
            raise ImmatureSignatureError("The token is not yet valid (iat)")

Appendix B

[Copilot]

Pull request overview

Updates PyJWT documentation to clarify that the leeway parameter applies to all time-based claims, including iat, reducing confusion around clock-skew handling during validation.

Changes:

• Update decode() / decode_complete() API docstrings to state leeway applies to exp, nbf, and iat.
• Add usage-guide documentation and an example showing iat validation with leeway.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
jwt/api_jwt.py	Clarifies leeway semantics in public decode API docstrings (exp/nbf/iat).
docs/usage.rst	Adds an iat + leeway explanation and example to the user-facing docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.