api.rst

API Reference

jwt

encode(payload, key, algorithm="HS256", headers=None, json_encoder=None)

Encode the payload as JSON Web Token.

param dict payload

JWT claims, e.g. dict(iss=..., aud=..., sub=...)

param str key

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

param str algorithm

algorithm to sign the token with, e.g. "ES256"

param dict headers

additional JWT header fields, e.g. dict(kid="my-key-id")

param json.JSONEncoder json_encoder

custom JSON encoder for payload and headers

rtype

str

returns

a JSON Web Token

decode(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0)

Verify the jwt token signature and return the token claims.

param str jwt

the token to be decoded

param str key

the key suitable for the allowed algorithm

param list algorithms

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*).

param dict options

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

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).

param Iterable audience

optional, the value for verify_aud check

param str issuer

optional, the value for verify_iss check

param float leeway

a time margin in seconds for the expiration check

rtype

dict

returns

the JWT claims

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.

param str jwt

the token to be decoded

param str key

the key suitable for the allowed algorithm

param list algorithms

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*).

param dict options

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

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).

param Iterable audience

optional, the value for verify_aud check

param str issuer

optional, the value for verify_iss check

param float leeway

a time margin in seconds for the expiration check

rtype

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

jwt.exceptions

Base exception when decode() fails on a token

Raised when a token cannot be decoded because it failed validation

Raised when a token's signature doesn't match the one provided as part of the token.

Raised when a token's exp claim indicates that it has expired

Raised when a token's aud claim does not match one of the expected audience values

Raised when a token's iss claim does not match the expected issuer

Raised when a token's iat claim is in the future

Raised when a token's nbf claim represents a time in the future

Raised when the specified key is not in the proper format

Raised when the specified algorithm is not recognized by PyJWT

Raised when a claim that is required to be present is not contained in the claimset