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