# 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 or bytes or jwt.PyJWK) –

      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. If `key` is a `jwt.PyJWK` object, by default the key algorithm will be used.

    - 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 or bytes or jwt.PyJWK) – the key suitable for the allowed algorithm

    - algorithms (list) –

      allowed algorithms, e.g. `["ES256"]` If `key` is a `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). 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

      - `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`).

    - audience (Union[str, 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

class jwt.PyJWK

  A class that represents a JSON Web Key.

  __init__(self, jwk_data, algorithm=None)
    Parameters:

      - data (dict) – The decoded JWK data.

      - algorithm (str or None) – The key algorithm. If not specific, the key’s `alg` will be used.

  static from_json(data, algorithm=None)
    Parameters:

      - data (str) – The JWK data, as a JSON string.

      - algorithm (str or None) – The key algorithm. If not specific, the key’s `alg` will be used.

    Returntype:

      jwt.PyJWK

    Create a `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.

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

      - `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`).

    - 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 non-numeric

class jwt.exceptions.ImmatureSignatureError

  Raised when a token’s `nbf` or `iat` claims represent 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