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 and headers

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 that exp (expiration) claim is present
- require_iat=False check that iat (issued at) claim is present
- require_nbf=False check that nbf (not before) claim is present
- verify_aud=False check that aud (audience) claim matches audience
- verify_iat=False check that iat (issued at) claim value is an integer
- verify_exp=False check that exp (expiration) claim value is OK
- verify_iss=False check that iss (issuer) claim matches issuer
- 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:

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