JWT API

This part of the documentation covers all the interfaces of joserfc.jwt.

class joserfc.jwt.BaseClaimsRegistry(**kwargs: ClaimsOption)

Requesting “claims” for JWT with the given conditions.

check_value(claim_name: str, value: Any) → None

Validates a given claim value based on predefined options.

Parameters:

• claim_name – The name of the claim to validate.

• value – The value of the claim to be validated.

Raises:

InvalidClaimError – If the value does not meet the claim’s validation requirements.

property essential_keys: set[str]

Returns the essential claim names.

validate(claims: dict[str, Any]) → None

Validates the provided claims against specified requirements and checks.

Parameters:

claims – A dictionary containing claims to validate.

Raises:

• InvalidClaimError – Raised if any claim fails validation.

• MissingClaimError – Raised if one or more essential keys are missing.

class joserfc.jwt.ClaimsOption

class joserfc.jwt.JWTClaimsRegistry(now: int | Callable[[], int] | None = None, leeway: int = 0, **kwargs: ClaimsOption)

A claims registry for validating JWT claims.

Parameters:

• now – timestamp of “now” time

• leeway – leeway time in seconds

• kwargs – claims options

property now: int

Returns the current timestamp.

validate_exp(value: int) → None

The “exp” (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the “exp” claim requires that the current date/time MUST be before the expiration date/time listed in the “exp” claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

validate_iat(value: int) → None

The “iat” (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

validate_nbf(value: int) → None

The “nbf” (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the “nbf” claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the “nbf” claim. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value MUST be a number containing a NumericDate value. Use of this claim is OPTIONAL.

class joserfc.jwt.Token(header: dict[str, Any], claims: dict[str, Any])

The extracted token object, which contains header and claims.

Parameters:

• header – the header part of the JWT

• claims – the payload part of the JWT

claims

payload claims in dict

header

header in dict

joserfc.jwt.check_sensitive_data(claims: dict[str, Any]) → None

Checks for sensitive data within a dictionary of claims and raises an error if any sensitive names or values are detected.

Parameters:

claims – JWT claims to check for sensitive data

Raises:

InsecureClaimError – if any sensitive names or values are detected

joserfc.jwt.decode(value: bytes | str, key: OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | JWERegistry | None = None, decoder_cls: Type[JSONDecoder] | None = None) → Token

Decode the JSON Web Token string with the given key, and validate it with the claims requests.

Parameters:

• value – text of the JWT

• key – key used to verify the signature

• algorithms – a list of allowed algorithms

• registry – a JWSRegistry or JWERegistry to use

• decoder_cls – A JSONDecoder subclass to use

Raises:

• BadSignatureError – when signature verification fails

• InvalidPayloadError – when payload is not a valid JSON object

joserfc.jwt.encode(header: dict[str, Any], claims: dict[str, Any], key: OctKey | RSAKey | ECKey | OKPKey | KeySet | Callable[[GuestProtocol], OctKey | RSAKey | ECKey | OKPKey | KeySet], algorithms: list[str] | None = None, registry: JWSRegistry | JWERegistry | None = None, encoder_cls: Type[JSONEncoder] | None = None, default_type: str | None = 'JWT') → str

Encode a JSON Web Token with the given header, and claims.

Parameters:

• header – A dict of the JWT header

• claims – A dict of the JWT claims to be encoded

• key – key used to sign the signature

• algorithms – a list of allowed algorithms

• registry – a JWSRegistry or JWERegistry to use

• encoder_cls – A JSONEncoder subclass to use

• default_type – default value of the typ header parameter