API Reference ============= .. module:: jwt .. function:: encode(payload, key, algorithm="HS256", headers=None, json_encoder=None) Encode the ``payload`` as JSON Web Token. :param dict payload: JWT claims, e.g. ``dict(iss=..., aud=..., sub=...)`` :param str key: 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 :param str algorithm: algorithm to sign the token with, e.g. ``"ES256"``. If ``headers`` includes ``alg``, it will be preferred to this parameter. :param dict headers: additional JWT header fields, e.g. ``dict(kid="my-key-id")``. :param json.JSONEncoder json_encoder: custom JSON encoder for ``payload`` and ``headers`` :rtype: str :returns: a JSON Web Token .. function:: decode(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0) Verify the ``jwt`` token signature and return the token claims. :param str jwt: the token to be decoded :param str key: the key suitable for the allowed algorithm :param list algorithms: 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\*). :param dict options: 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``). :param Iterable audience: optional, the value for ``verify_aud`` check :param str issuer: optional, the value for ``verify_iss`` check :param float leeway: a time margin in seconds for the expiration check :rtype: dict :returns: the JWT claims .. module:: jwt.api_jwt .. function:: 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. :param str jwt: the token to be decoded :param str key: the key suitable for the allowed algorithm :param list algorithms: 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\*). :param dict options: 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``). :param Iterable audience: optional, the value for ``verify_aud`` check :param str issuer: optional, the value for ``verify_iss`` check :param float leeway: a time margin in seconds for the expiration check :rtype: 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 ---------- .. currentmodule:: jwt.exceptions .. class:: InvalidTokenError Base exception when ``decode()`` fails on a token .. class:: DecodeError Raised when a token cannot be decoded because it failed validation .. class:: InvalidSignatureError Raised when a token's signature doesn't match the one provided as part of the token. .. class:: ExpiredSignatureError Raised when a token's ``exp`` claim indicates that it has expired .. class:: InvalidAudienceError Raised when a token's ``aud`` claim does not match one of the expected audience values .. class:: InvalidIssuerError Raised when a token's ``iss`` claim does not match the expected issuer .. class:: InvalidIssuedAtError Raised when a token's ``iat`` claim is in the future .. class:: ImmatureSignatureError Raised when a token's ``nbf`` claim represents a time in the future .. class:: InvalidKeyError Raised when the specified key is not in the proper format .. class:: InvalidAlgorithmError Raised when the specified algorithm is not recognized by PyJWT .. class:: MissingRequiredClaimError Raised when a claim that is required to be present is not contained in the claimset