API Reference

jwt.encode(payload, key, algorithm='HS256', headers=None, json_encoder=None)

Encode the payload as JSON Web Token.

Parameters:

payload (dict) – JWT claims, e.g. dict(iss=..., aud=..., sub=...)
key (str or bytes or jwt.PyJWK) –
a key suitable for the chosen algorithm:
- for asymmetric algorithms: PEM-formatted private key, a multiline string
- for symmetric algorithms: plain string, sufficiently long for security
algorithm (str) – algorithm to sign the token with, e.g. "ES256". If headers includes alg, it will be preferred to this parameter. If key is a jwt.PyJWK object, by default the key algorithm will be used.
headers (dict) – additional JWT header fields, e.g. dict(kid="my-key-id").
json_encoder (json.JSONEncoder) – custom JSON encoder for payload and headers

Return type:

str

Returns:

a JSON Web Token

jwt.decode(jwt, key='', algorithms=None, options=None, audience=None, issuer=None, leeway=0)

Verify the jwt token signature and return the token claims.

Parameters:

jwt (str) – the token to be decoded
key (str or bytes or jwt.PyJWK) – the key suitable for the allowed algorithm
algorithms (list) –
allowed algorithms, e.g. ["ES256"] If key is a jwt.PyJWK object, allowed algorithms will default to the key algorithm.

Warning

Do not compute the algorithms parameter based on the alg from the token itself, or on any other data that an attacker may be able to influence, as that might expose you to various vulnerabilities (see RFC 8725 §2.1). Instead, either hard-code a fixed value for algorithms, or configure it in the same place you configure the key. Make sure not to mix symmetric and asymmetric algorithms that interpret the key in different ways (e.g. HS* and RS*).
options (dict) –
extended decoding and validation options
- verify_signature=True verify the JWT cryptographic signature
- require=[] list of claims that must be present. Example: require=["exp", "iat", "nbf"]. Only verifies that the claims exists. Does not verify that the claims are valid.
- verify_aud=verify_signature check that aud (audience) claim matches audience
- verify_iss=verify_signature check that iss (issuer) claim matches issuer
- verify_exp=verify_signature check that exp (expiration) claim value is in the future
- verify_iat=verify_signature check that iat (issued at) claim value is an integer
- verify_nbf=verify_signature check that nbf (not before) claim value is in the past
- strict_aud=False check that the aud claim is a single value (not a list), and matches audience exactly
Warning

exp, iat and nbf will only be verified if present. Please pass respective value to require if you want to make sure that they are always present (and therefore always verified if verify_exp, verify_iat, and verify_nbf respectively is set to True).
audience (Union[str, Iterable]) – optional, the value for verify_aud check
issuer (str) – optional, the value for verify_iss check
leeway (float) – a time margin in seconds for the expiration check

Return type:

dict

Returns:

the JWT claims

class jwt.PyJWK

A class that represents a JSON Web Key.

__init__(self, jwk_data, algorithm=None)

Parameters:

data (dict) – The decoded JWK data.
algorithm (str or None) – The key algorithm. If not specific, the key’s alg will be used.

static from_json(data, algorithm=None)

Parameters:

data (str) – The JWK data, as a JSON string.
algorithm (str or None) – The key algorithm. If not specific, the key’s alg will be used.

Returntype:

jwt.PyJWK

Create a jwt.PyJWK object from a JSON string.

property algorithm_name

Type:: str

The name of the algorithm used by the key.

property Algorithm: The Algorithm class associated with the key.

property key_type

Type:: str or None

The kty property from the JWK.

property key_id

Type:: str or None

The kid property from the JWK.

property public_key_use

Type:: str or None

The use property from the JWK.

jwt.api_jwt.decode_complete(jwt, key='', algorithms=None, options=None, audience=None, issuer=None, leeway=0)

Identical to jwt.decode except for return value which is a dictionary containing the token header (JOSE Header), the token payload (JWT Payload), and token signature (JWT Signature) on the keys “header”, “payload”, and “signature” respectively.

Parameters:

jwt (str) – the token to be decoded
key (str) – the key suitable for the allowed algorithm
algorithms (list) –
allowed algorithms, e.g. ["ES256"]

Warning

Do not compute the algorithms parameter based on the alg from the token itself, or on any other data that an attacker may be able to influence, as that might expose you to various vulnerabilities (see RFC 8725 §2.1). Instead, either hard-code a fixed value for algorithms, or configure it in the same place you configure the key. Make sure not to mix symmetric and asymmetric algorithms that interpret the key in different ways (e.g. HS* and RS*).
options (dict) –
extended decoding and validation options
- verify_signature=True verify the JWT cryptographic signature
- require=[] list of claims that must be present. Example: require=["exp", "iat", "nbf"]. Only verifies that the claims exists. Does not verify that the claims are valid.
- verify_aud=verify_signature check that aud (audience) claim matches audience
- verify_iss=verify_signature check that iss (issuer) claim matches issuer
- verify_exp=verify_signature check that exp (expiration) claim value is in the future
- verify_iat=verify_signature check that iat (issued at) claim value is an integer
- verify_nbf=verify_signature check that nbf (not before) claim value is in the past
- strict_aud=False check that the aud claim is a single value (not a list), and matches audience exactly
Warning

exp, iat and nbf will only be verified if present. Please pass respective value to require if you want to make sure that they are always present (and therefore always verified if verify_exp, verify_iat, and verify_nbf respectively is set to True).
audience (Iterable) – optional, the value for verify_aud check
issuer (str) – optional, the value for verify_iss check
leeway (float) – a time margin in seconds for the expiration check

Return type:

dict

Returns:

Decoded JWT with the JOSE Header on the key header, the JWS Payload on the key payload, and the JWS Signature on the key signature.

Note

TODO: Document PyJWS class

Exceptions

class jwt.exceptions.InvalidTokenError: Base exception when decode() fails on a token

class jwt.exceptions.DecodeError: Raised when a token cannot be decoded because it failed validation

class jwt.exceptions.InvalidSignatureError: Raised when a token’s signature doesn’t match the one provided as part of the token.

class jwt.exceptions.ExpiredSignatureError: Raised when a token’s exp claim indicates that it has expired

class jwt.exceptions.InvalidAudienceError: Raised when a token’s aud claim does not match one of the expected audience values

class jwt.exceptions.InvalidIssuerError: Raised when a token’s iss claim does not match the expected issuer

class jwt.exceptions.InvalidIssuedAtError: Raised when a token’s iat claim is non-numeric

class jwt.exceptions.ImmatureSignatureError: Raised when a token’s nbf or iat claims represent a time in the future

class jwt.exceptions.InvalidKeyError: Raised when the specified key is not in the proper format

class jwt.exceptions.InvalidAlgorithmError: Raised when the specified algorithm is not recognized by PyJWT

class jwt.exceptions.MissingRequiredClaimError: Raised when a claim that is required to be present is not contained in the claimset