PyJWT

PyJWT is the de facto standard library for working with JSON Web Tokens in Python. It provides simple encode()/decode() functions covering the full RFC 7519 surface — issuer, audience, expiration, and not-before claim validation — plus pluggable signing algorithms for HMAC, RSA, ECDSA, and Ed25519/Ed448 keys.

Beyond the core encode/decode API, PyJWT ships a JWKS client (PyJWKClient) for fetching and caching signing keys from an identity provider’s JSON Web Key Set endpoint, making it a common building block for verifying tokens issued by OAuth/OIDC providers such as Auth0, Okta, and Firebase.

What You Get

• encode()/decode() functions supporting HS256/384/512, RS256/384/512, ES256/384/512/256K, PS256/384/512, and EdDSA algorithms
• Built-in validation of standard claims: exp, nbf, iat, aud, and iss, with configurable leeway for clock skew
• PyJWKClient for fetching, caching, and rotating signing keys from a remote JWKS endpoint
• PyJWK/PyJWKSet classes implementing RFC 7517 JSON Web Key parsing
• Custom exception hierarchy (ExpiredSignatureError, InvalidAudienceError, etc.) for precise error handling
• Optional cryptography integration for asymmetric algorithms, kept as an extra so HMAC-only users avoid the dependency

Common Use Cases

• Issuing and verifying stateless session/auth tokens for a Python API backend
• Validating tokens issued by an external OAuth/OIDC identity provider using its published JWKS endpoint
• Signing short-lived, single-purpose tokens (password reset links, email verification, webhook signing)
• Service-to-service authentication between internal microservices using shared HMAC secrets

Under The Hood

Architecture The library centers on api_jwt.py (the high-level encode/decode functions and claim validation) which delegates cryptographic signing/verification to api_jws.py, itself backed by an algorithms.py registry mapping algorithm names (HS256, RS256, ES256, EdDSA, …) to key-handling implementations. api_jwk.py implements RFC 7517 JWK parsing, and jwks_client.py layers an HTTP-fetching, TTL-caching client (PyJWKClient, jwk_set_cache.py) on top of it for remote key resolution — a common need when verifying third-party-issued tokens.

Tech Stack Pure Python core with the cryptography package as an optional dependency (declared as an extra) for RSA/EC/EdDSA algorithms, so HMAC-only consumers don’t have to install a C-extension-backed cryptography library. Built with setuptools, targets Python 3.9+, and uses ruff for linting per ruff.toml.

Code Quality Comprehensive test suite (tests/test_api_jwt.py, test_algorithms.py, test_jwks_client.py, etc.) with fixture keys for every supported algorithm family under tests/keys/, plus a dedicated test_advisory.py covering historical CVEs (e.g. the none algorithm confusion attack) as regression tests — notable given JWT libraries’ history of signature-verification bypass vulnerabilities. Uses coverage with a checked-in codecov.yml for CI coverage gating.

API Design The functional encode(payload, key, algorithm) / decode(token, key, algorithms=[...]) signature keeps the common path minimal, while an explicit exception hierarchy (ExpiredSignatureError, InvalidSignatureError, InvalidAudienceError) lets callers distinguish failure modes precisely instead of parsing string messages. Requiring algorithms=[...] explicitly on decode (rather than trusting the token’s own header) is a deliberate API safety choice that prevents algorithm-confusion attacks.