diff options
author | Dima Tisnek <dimaqq@gmail.com> | 2020-04-27 08:52:22 +0900 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-04-26 19:52:22 -0400 |
commit | c2c91a7bb504f9ff10387972b8ce9353493ed773 (patch) | |
tree | e55f2ceb8ca8e62c9f8288bb97489a990c1b48cb | |
parent | 2b564094a6d71bc9778fa126dbe05e8daed52141 (diff) | |
download | pyjwt-c2c91a7bb504f9ff10387972b8ce9353493ed773.tar.gz |
Document top-level .encode and .decode to close #459 (#482)
Co-authored-by: José Padilla <jpadilla@webapplicate.com>
-rw-r--r-- | docs/api.rst | 62 | ||||
-rw-r--r-- | docs/usage.rst | 6 |
2 files changed, 64 insertions, 4 deletions
diff --git a/docs/api.rst b/docs/api.rst index 08b6991..3f66173 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,7 +3,67 @@ API Reference .. module:: jwt -TODO: Document PyJWS / PyJWT classes +.. 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"`` + :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="", verify=True, algorithms=None, options=None, audience=None, issuer=None, leeway=0, verify_expiration=True) + + Verify the ``jwt`` token signature and return the token claims. + + :param str|bytes jwt: the token to be decoded + :param str key: the key suitable for the allowed algorithm + :param bool verify: whether to verify the JWT signature, on by default + + .. deprecated:: 1.5.1 + to disable signature validation, use ``options=(verify_signature=False)`` + + :param list algorithms: 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. + + :param dict options: 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 + * ``verify_expiration`` + + .. deprecated:: 1.2.0 + Use ``verify_exp`` instead + + + :param str|iterable audience: optional, the value for ``verify_aud`` check + :param str issuer: optional, the value for ``verify_iss`` check + :param int|float leeway: a time margin in seconds for the expiration check + :param bool verify_expiration: + + .. deprecated:: 1.2.0 + Use ``options=(verify_exp=...)`` instead + + :rtype: dict + :returns: the JWT claims + +.. note:: TODO: Document PyJWS / PyJWT classes Exceptions ---------- diff --git a/docs/usage.rst b/docs/usage.rst index fbd0ebb..d2da71a 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -2,7 +2,7 @@ Usage Examples ============== Encoding & Decoding Tokens with HS256 --------------------------------------- +------------------------------------- .. code-block:: python @@ -27,7 +27,7 @@ Encoding & Decoding Tokens with RS256 (RSA) {'some': 'payload'} Specifying Additional Headers ---------------------------------- +----------------------------- .. code-block:: python @@ -36,7 +36,7 @@ Specifying Additional Headers Reading the Claimset without Validation ------------------------------------------ +--------------------------------------- If you wish to read the claimset of a JWT without performing validation of the signature or any of the registered claim names, you can set the ``verify`` |