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"]

    Warning

    Do not compute the algorithms parameter based on the alg 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 for algorithms, or configure it in the same place you configure the key. Make sure not to mix symmetric and asymmetric algorithms that interpret the key 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 if verify_signature is False.
      Check that aud (audience) claim matches audience
    • verify_iat=True but will be ignored if verify_signature is False.
      Check that iat (issued at) claim value is an integer
    • verify_exp=True but will be ignored if verify_signature is False.
      Check that exp (expiration) claim value is OK
    • verify_iss=True but will be ignored if verify_signature is False.
      Check that iss (issuer) claim matches issuer
    • verify_nbf=True but will be ignored if verify_signature is False.
      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:

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