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) –
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"
. Ifheaders
includesalg
, it will be preferred to this parameter. - headers (dict) – additional JWT header fields, e.g.
dict(kid="my-key-id")
. - json_encoder (json.JSONEncoder) – custom JSON encoder for
payload
andheaders
Return type: Returns: a JSON Web Token
- payload (dict) – JWT claims, e.g.
-
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) – the key suitable for the allowed algorithm
- algorithms (list) –
allowed algorithms, e.g.
["ES256"]
Warning
Do not compute the
algorithms
parameter based on thealg
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 foralgorithms
, or configure it in the same place you configure thekey
. Make sure not to mix symmetric and asymmetric algorithms that interpret thekey
in different ways (e.g. HS* and RS*). - options (dict) –
extended decoding and validation options
verify_signature=True
verify the JWT cryptographic signaturerequire=[]
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 thataud
(audience) claim matchesaudience
verify_iss=verify_signature
check thatiss
(issuer) claim matchesissuer
verify_exp=verify_signature
check thatexp
(expiration) claim value is in the futureverify_iat=verify_signature
check thatiat
(issued at) claim value is an integerverify_nbf=verify_signature
check thatnbf
(not before) claim value is in the past
Warning
exp
,iat
andnbf
will only be verified if present. Please pass respective value torequire
if you want to make sure that they are always present (and therefore always verified ifverify_exp
,verify_iat
, andverify_nbf
respectively is set toTrue
). - Iterable] audience (Union[str,) – 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: 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.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 thealg
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 foralgorithms
, or configure it in the same place you configure thekey
. Make sure not to mix symmetric and asymmetric algorithms that interpret thekey
in different ways (e.g. HS* and RS*). - options (dict) –
extended decoding and validation options
verify_signature=True
verify the JWT cryptographic signaturerequire=[]
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 thataud
(audience) claim matchesaudience
verify_iss=verify_signature
check thatiss
(issuer) claim matchesissuer
verify_exp=verify_signature
check thatexp
(expiration) claim value is in the futureverify_iat=verify_signature
check thatiat
(issued at) claim value is an integerverify_nbf=verify_signature
check thatnbf
(not before) claim value is in the past
Warning
exp
,iat
andnbf
will only be verified if present. Please pass respective value torequire
if you want to make sure that they are always present (and therefore always verified ifverify_exp
,verify_iat
, andverify_nbf
respectively is set toTrue
). - 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: Returns: Decoded JWT with the JOSE Header on the key
header
, the JWS Payload on the keypayload
, and the JWS Signature on the keysignature
.
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 in the future
-
class
jwt.exceptions.
ImmatureSignatureError
¶ Raised when a token’s
nbf
claim represents 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