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". If headers includes alg, it will be preferred to this parameter.
  • 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

    • verify_signature=True verify the JWT cryptographic signature
    • require=[] list of claims that must be present. Example: require=["exp", "iat", "nbf"]. Only verifies that the claims exists. Does not verify that the claims are valid.
    • verify_aud=verify_signature check that aud (audience) claim matches audience
    • verify_iss=verify_signature check that iss (issuer) claim matches issuer
    • verify_exp=verify_signature check that exp (expiration) claim value is in the future
    • verify_iat=verify_signature check that iat (issued at) claim value is an integer
    • verify_nbf=verify_signature check that nbf (not before) claim value is in the past

    Warning

    exp, iat and nbf will only be verified if present. Please pass respective value to require if you want to make sure that they are always present (and therefore always verified if verify_exp, verify_iat, and verify_nbf respectively is set to True).

  • Iterable] audience (Union[str,) – 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
jwt.api_jwt.decode_complete(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0)

Identical to jwt.decode except for return value which is a dictionary containing the token header (JOSE Header), the token payload (JWT Payload), and token signature (JWT Signature) on the keys “header”, “payload”, and “signature” respectively.

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

    • verify_signature=True verify the JWT cryptographic signature
    • require=[] list of claims that must be present. Example: require=["exp", "iat", "nbf"]. Only verifies that the claims exists. Does not verify that the claims are valid.
    • verify_aud=verify_signature check that aud (audience) claim matches audience
    • verify_iss=verify_signature check that iss (issuer) claim matches issuer
    • verify_exp=verify_signature check that exp (expiration) claim value is in the future
    • verify_iat=verify_signature check that iat (issued at) claim value is an integer
    • verify_nbf=verify_signature check that nbf (not before) claim value is in the past

    Warning

    exp, iat and nbf will only be verified if present. Please pass respective value to require if you want to make sure that they are always present (and therefore always verified if verify_exp, verify_iat, and verify_nbf respectively is set to True).

  • 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:

Decoded JWT with the JOSE Header on the key header, the JWS Payload on the key payload, and the JWS Signature on the key signature.

Note

TODO: Document PyJWS class

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