JWT API

jose.jwt.decode(token, key, algorithms=None, options=None, audience=None, issuer=None, subject=None, access_token=None)

Verifies a JWT string’s signature and validates reserved claims.

Parameters:
  • token (str) – A signed JWS to be verified.
  • key (str) – A key to attempt to verify the payload with.
  • algorithms (str or list) – Valid algorithms that should be used to verify the JWS.
  • audience (str) – The intended audience of the token. If the “aud” claim is included in the claim set, then the audience must be included and must equal the provided claim.
  • issuer (str or iterable) – Acceptable value(s) for the issuer of the token. If the “iss” claim is included in the claim set, then the issuer must be given and the claim in the token must be among the acceptable values.
  • subject (str) – The subject of the token. If the “sub” claim is included in the claim set, then the subject must be included and must equal the provided claim.
  • access_token (str) – An access token returned alongside the id_token during the authorization grant flow. If the “at_hash” claim is included in the claim set, then the access_token must be included, and it must match the “at_hash” claim.
  • options (dict) –

    A dictionary of options for skipping validation steps.

    defaults = {
    ‘verify_signature’: True, ‘verify_aud’: True, ‘verify_iat’: True, ‘verify_exp’: True, ‘verify_nbf’: True, ‘verify_iss’: True, ‘verify_sub’: True, ‘verify_jti’: True, ‘leeway’: 0,

    }

Returns:

The dict representation of the claims set, assuming the signature is valid and all requested data validation passes.

Return type:

dict

Raises:

JWTError – If the signature is invalid in any way.

Examples

>>> payload = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhIjoiYiJ9.jiMyrsmD8AoHWeQgmxZ5yq8z0lXS67_QGs52AzC8Ru8'
>>> jwt.decode(payload, 'secret', algorithms='HS256')
jose.jwt.encode(claims, key, algorithm='HS256', headers=None, access_token=None)

Encodes a claims set and returns a JWT string.

JWTs are JWS signed objects with a few reserved claims.

Parameters:
  • claims (dict) – A claims set to sign
  • key (str) – The key to use for signing the claim set
  • algorithm (str, optional) – The algorithm to use for signing the the claims. Defaults to HS256.
  • headers (dict, optional) – A set of headers that will be added to the default headers. Any headers that are added as additional headers will override the default headers.
  • access_token (str, optional) – If present, the ‘at_hash’ claim will be calculated and added to the claims present in the ‘claims’ parameter.
Returns:

The string representation of the header, claims, and signature.

Return type:

str

Raises:

JWTError – If there is an error encoding the claims.

Examples

>>> jwt.encode({'a': 'b'}, 'secret', algorithm='HS256')
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhIjoiYiJ9.jiMyrsmD8AoHWeQgmxZ5yq8z0lXS67_QGs52AzC8Ru8'
jose.jwt.get_unverified_claims(token)

Returns the decoded claims without verification of any kind.

Parameters:token (str) – A signed JWT to decode the headers from.
Returns:The dict representation of the token claims.
Return type:dict
Raises:JWTError – If there is an exception decoding the token.
jose.jwt.get_unverified_header(token)

Returns the decoded headers without verification of any kind.

Parameters:token (str) – A signed JWT to decode the headers from.
Returns:The dict representation of the token headers.
Return type:dict
Raises:JWTError – If there is an exception decoding the token.
jose.jwt.get_unverified_headers(token)

Returns the decoded headers without verification of any kind.

This is simply a wrapper of get_unverified_header() for backwards compatibility.

Parameters:token (str) – A signed JWT to decode the headers from.
Returns:The dict representation of the token headers.
Return type:dict
Raises:JWTError – If there is an exception decoding the token.