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: 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
require=[]
list of claims that must be present. E.g.require=["exp", "iat", "nbf"]
.- Only verifies that the claims exists. Does NOT verify that the claims are valid.
verify_aud=True
but will be ignored ifverify_signature
isFalse
.- Check that
aud
(audience) claim matchesaudience
verify_iat=True
but will be ignored ifverify_signature
isFalse
.- Check that
iat
(issued at) claim value is an integer
verify_exp=True
but will be ignored ifverify_signature
isFalse
.- Check that
exp
(expiration) claim value is OK
verify_iss=True
but will be ignored ifverify_signature
isFalse
.- Check that
iss
(issuer) claim matchesissuer
verify_nbf=True
but will be ignored ifverify_signature
isFalse
.- Check that
nbf
(not before) is in the past
verify_signature=True
verify the JWT cryptographic signature
- 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: 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