.. 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 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
:type key: str or bytes or jwt.PyJWK
:param str algorithm: algorithm to sign the token with, e.g. ``"ES256"``.
If ``headers`` includes ``alg``, it will be preferred to this parameter.
If ``key`` is a :class:`jwt.PyJWK` object, by default the key algorithm will be used.
: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 key: the key suitable for the allowed algorithm
:type key: str or bytes or jwt.PyJWK
:param list algorithms: allowed algorithms, e.g. ``["ES256"]``
If ``key`` is a :class:`jwt.PyJWK` object, allowed algorithms will default to the key algorithm.
.. 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
<https://www.rfc-editor.org/rfc/rfc8725.html#section-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
* ``strict_aud=False`` check that the ``aud`` claim is a single value (not a list), and matches ``audience`` exactly
.. 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 audience: optional, the value for ``verify_aud`` check
:type audience: Union[str, Iterable]
: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
A class that represents a JSON Web Key.
.. method:: __init__(self, jwk_data, algorithm=None) :param dict data: The decoded JWK data. :param algorithm: The key algorithm. If not specific, the key's ``alg`` will be used. :type algorithm: str or None
.. staticmethod:: from_json(data, algorithm=None) :param str data: The JWK data, as a JSON string. :param algorithm: The key algorithm. If not specific, the key's ``alg`` will be used. :type algorithm: str or None :returntype: jwt.PyJWK Create a :class:`jwt.PyJWK` object from a JSON string.
.. property:: algorithm_name :type: str The name of the algorithm used by the key.
.. property:: Algorithm The ``Algorithm`` class associated with the key.
.. property:: key_type :type: str or None The ``kty`` property from the JWK.
.. property:: key_id :type: str or None The ``kid`` property from the JWK.
.. property:: public_key_use :type: str or None The ``use`` property from the JWK.
.. 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
<https://www.rfc-editor.org/rfc/rfc8725.html#section-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
* ``strict_aud=False`` check that the ``aud`` claim is a single value (not a list), and matches ``audience`` exactly
.. 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
.. currentmodule:: jwt.exceptions
Base exception when decode() fails on a token
Raised when a token cannot be decoded because it failed validation
Raised when a token's signature doesn't match the one provided as part of the token.
Raised when a token's exp claim indicates that it has expired
Raised when a token's aud claim does not match one of the expected
audience values
Raised when a token's iss claim does not match the expected issuer
Raised when a token's iat claim is non-numeric
Raised when a token's nbf or iat claims represent a time in the future
Raised when the specified key is not in the proper format
Raised when the specified algorithm is not recognized by PyJWT
Raised when a claim that is required to be present is not contained in the claimset