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:
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) – the key suitable for the allowed algorithm
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 signature
audience (Iterable) – optional, the value for
verify_aud
checkissuer (str) – optional, the value for
verify_iss
checkleeway (float) – a time margin in seconds for the expiration check
- 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