jwt
import jwt
The jwt module provides a complete implementation of JSON Web Tokens (JWT) as defined in RFC 7519, with support for signing, verification, and inspection of tokens using HMAC, RSA-PSS, ECDSA, and Ed25519 algorithm families.
Supported algorithms:
- HS256/HS384/HS512: HMAC with SHA-256/384/512
- PS256/PS384/PS512: RSASSA-PSS with SHA-256/384/512. This module deliberately supports PS-family, not RS-family (RSASSA-PKCS1-v1_5) algorithms, because they’re older, deterministic standard that lacks a formal security proof and because they’re mostly deterministic while the RSASSA-PSS are probabilistic.
Also, while PKCS#1 v1.5 is simpler to set up, but its structural rigidity has led to historical implementation flaws in encryption (like Bleichenbacher attacks), making PSS cleaner and safer against misuse.
- ES256: ECDSA P-256 with SHA-256
- ES384: ECDSA P-384 with SHA-384
- EdDSA: Ed25519 (RFC 8037)
- none: Unsecured token (no signature, explicit opt-in required)
Signature verification uses a constant-time comparison for the HMAC algorithms (to prevent timing attacks against the shared secret) and the underlying public-key verification routine for every asymmetric algorithm.
Quick start
import jwt
# sign a token
var token = jwt.sign({ user_id: 42, role: 'admin' }, 'secret')
# verify and decode the token
var payload = jwt.verify(token, 'secret')
echo payload.user_id # 42
For applications verifying many tokens with the same configuration,
prefer a Verifier (see [[jwt.Verifier]]) over repeating options on
every verify() call. Likewise, prefer a Signer (see [[jwt.Signer]])
for repeated signing.
When keys are resolved by kid from a JSON Web Key Set rather than
fixed ahead of time, see [[jwt.Jwks]] and [[jwt.verify_with_jwks]].
The jwt API
Every public name in jwt, wherever it is declared. Each links to the
page that documents it.
| Name | Kind | Summary |
|---|---|---|
jwt.AlgorithmError | class | Raised when an algorithm specified in a token header is not supported by this module, when the caller… |
jwt.ClaimError | class | Raised when a required claim is absent from the token payload, or when a registered claim (iss, aud, sub)… |
jwt.EDDSA | constant | Ed25519 (EdDSA, RFC 8037) signing algorithm identifier. |
jwt.ES256 | constant | ECDSA P-256 with SHA-256 signing algorithm identifier. |
jwt.ES384 | constant | ECDSA P-384 with SHA-384 signing algorithm identifier. |
jwt.HS256 | constant | HMAC-SHA256 signing algorithm identifier. |
jwt.HS384 | constant | HMAC-SHA384 signing algorithm identifier. |
jwt.HS512 | constant | HMAC-SHA512 signing algorithm identifier. |
jwt.Jwks | class | Parses a JSON Web Key Set document (a dict shaped like { keys: [...] }, exactly what json.decode() on a… |
jwt.JwtError | class | Base error class for all errors raised by the jwt module. |
jwt.MalformedTokenError | class | Raised when a token cannot be decoded because its structure is not valid. |
jwt.NONE | constant | Unsecured algorithm identifier. |
jwt.PS256 | constant | RSA-PSS-SHA256 signing algorithm identifier. |
jwt.PS384 | constant | RSA-PSS-SHA384 signing algorithm identifier. |
jwt.PS512 | constant | RSA-PSS-SHA512 signing algorithm identifier. |
jwt.SignatureError | class | Raised when a token’s signature does not match its header and payload. |
jwt.Signer | class | A reusable token signer that holds a fixed secret and set of default signing options. |
jwt.Token | class | Represents a decoded JWT. |
jwt.TokenExpiredError | class | Raised when a token’s temporal claims fail validation: |
jwt.Verifier | class | A reusable token verifier that holds a fixed secret and set of options. |
jwt.decode | function | Decodes a JWT string into a Token instance without performing signature verification or claim validation. |
jwt.encode | function | Encodes a header dictionary and payload dictionary into a signed JWT string. |
jwt.expires_in | function | Returns the number of seconds until the token expires, based on its exp claim and the current clock. |
jwt.header | function | Returns the decoded header dictionary of a token without verifying its signature. |
jwt.is_expired | function | Returns true when the token’s exp claim is in the past, without verifying the signature. |
jwt.payload | function | Returns the decoded payload dictionary of a token without verifying its signature. |
jwt.sign | function | Creates and signs a new JWT from the given payload. |
jwt.verify | function | Verifies a JWT string and returns its payload (or the full Token when options.complete is true). |
jwt.verify_with_jwks | function | Verifies a token by resolving its signing key from a JWKS document rather than a single fixed secret. |
Submodules
| Module | Reached as | Summary |
|---|---|---|
jwt.codec | jwt.* | Algorithm identifiers and the low-level encoding helpers core.zu builds encode()/verify() out of:… |
jwt.core | jwt.* | The core encode/decode/sign/verify functions the rest of the jwt module is built on. |
jwt.errors | jwt.* | The full error hierarchy raised by the jwt module. |
jwt.jwks | jwt.* | Jwks, plus verify_with_jwks(): resolving a token’s signing key from a JSON Web Key Set (RFC 7517) by its… |
jwt.signer | jwt.* | Signer, a reusable configured wrapper around core.sign(). |
jwt.token | jwt.* | The Token class returned by decode() and verify() (when options.complete is set). |
jwt.verifier | jwt.* | Verifier, a reusable configured wrapper around core.verify(). |
2026, Richard Ore and The Zuri Contributors