How to verify a JWT with a JWKS in Python

1import jwt  # PyJWT: pip install "pyjwt[crypto]==2.15.1"
2 
3# Fetches the key set over HTTPS, caches it, and fetches again when a kid is unknown
4jwks_client = jwt.PyJWKClient("https://issuer.example.com/.well-known/jwks.json")
5 
6 
7def verify_access_token(token: str) -> dict:
8    signing_key = jwks_client.get_signing_key_from_jwt(token)  # selected by the token's kid
9    return jwt.decode(
10        token,
11        signing_key.key,
12        algorithms=["ES256"],  # never take the algorithm from the token
13        issuer="https://issuer.example.com",
14        audience="api://orders",
15        options={"require": ["exp", "iss", "aud"]},
16    )

1with open("tokens.txt") as f:
2    for line in f:
3        label, token = line.split()
4        try:
5            claims = verify_access_token(token)
6            print(f"{label}: accepted, sub={claims['sub']}")
7        except jwt.PyJWTError as e:  # also covers PyJWKClientError
8            print(f"{label}: rejected: {type(e).__name__}: {e}")

How it works

1. PyJWKClient(url) downloads the JWKS on first use and caches it for 300 seconds (lifespan).
2. get_signing_key_from_jwt(token) reads the unverified header, finds the key with that kid, and refetches the set once if the kid is unknown and the 30-second cooldown has passed.
3. jwt.decode verifies the signature with signing_key.key, then exp, iss and aud; options={"require": […]} also rejects tokens that lack those claims.
4. Every error derives from jwt.PyJWTError: InvalidAudienceError, InvalidIssuerError, ExpiredSignatureError and, for an unknown key, PyJWKClientError.

Gotchas

• algorithms=["ES256"] is mandatory in PyJWT 2 — and it must come from your configuration, not from the token header, or the token chooses how it is verified.
• If the token has an aud but decode is called without audience=, PyJWT raises InvalidAudienceError: Invalid audience. That is deliberate: pass the audience your service expects instead of disabling the check.
• The client is meant to live as long as the process. Creating a PyJWKClient per request discards the cache and fetches the JWKS for every token.
• Fetch errors surface as PyJWKClientConnectionError (a subclass of PyJWKClientError), so a down JWKS endpoint looks like an invalid token unless you catch it separately and answer with a 5xx.

Related recipes

• How to sign a JWT with ES256 in Python
• How to verify an ES256 JWT in Python
• How to compute a JWK thumbprint (RFC 7638) in Python
• How to verify a JWT with a JWKS in Node.js
• How to verify a JWT with a JWKS in Go