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"
- 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: bytes
Returns: a JSON Web Token
- payload (dict) – JWT claims, e.g.
-
jwt.
decode
(jwt, key="", verify=True, algorithms=None, options=None, audience=None, issuer=None, leeway=0, verify_expiration=True)¶ Verify the
jwt
token signature and return the token claims.Parameters: - jwt (str|bytes) – the token to be decoded
- key (str) – the key suitable for the allowed algorithm
- verify (bool) –
whether to verify the JWT signature, on by default
Deprecated since version 1.5.1: to disable signature validation, use
options=(verify_signature=False)
- algorithms (list) –
allowed algorithms, e.g.
["ES256"]
Note
It is highly recommended to specify the expected
algorithms
.Note
It is insecure to mix symmetric and asymmetric algorithms because they require different kinds of keys.
- options (dict) –
extended decoding and validation options
require_exp=False
check thatexp
(expiration) claim is presentrequire_iat=False
check thatiat
(issued at) claim is presentrequire_nbf=False
check thatnbf
(not before) claim is presentverify_aud=False
check thataud
(audience) claim matchesaudience
verify_iat=False
check thatiat
(issued at) claim value is an integerverify_exp=False
check thatexp
(expiration) claim value is OKverify_iss=False
check thatiss
(issuer) claim matchesissuer
verify_signature=True
verify the JWT cryptographic signatureverify_expiration
Deprecated since version 1.2.0: Use
verify_exp
instead
- audience (iterable) – optional, the value for
verify_aud
check - issuer (str) – optional, the value for
verify_iss
check - leeway (int|float) – a time margin in seconds for the expiration check
- verify_expiration (bool) –
Deprecated since version 1.2.0: Use
options=(verify_exp=...)
instead
Return type: dict
Returns: the JWT claims
Note
TODO: Document PyJWS / PyJWT classes
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