API¶

EasyJWT provides a simple interface to creating and verifying JSON Web Tokens (JWTs) in Python. It allows you to once define the claims of the JWT, and to then create and accept tokens with these claims without having to check if all the required data is given or if the token actually is the one you expect.

See the included README file or the documentation for details on how to use EasyJWT.

Contents

Classes
Enumerations
Errors
- Creation Errors
- Verification Errors
Modules
- restoration
Types

Classes¶

This section lists all classes defined by EasyJWT.

class EasyJWT(key: str)[source]¶

Bases: object

The base class for representing JSON Web Tokens (JWT).

To use a JWT, you have to create a subclass inheriting from EasyJWT. All public instance variables of this class (that is, all instance variables not starting with an underscore) will make up the claim set of your token (there will be a few meta claims in the token as well that EasyJWT needs to verify the token).

Parameters: key – The private key that is used for encoding and decoding the token.

algorithm: ClassVar[easyjwt.enums.Algorithm] = 'HS256'¶

The algorithm used for encoding the token.

When changing the algorithm, its old value must be added to previous_algorithms so that old tokens may still be decoded properly.

This variable is not part of the claim set.

previous_algorithms: ClassVar[Set[easyjwt.enums.Algorithm]] = {}¶

All algorithms that have previously been used for encoding the token, needed for decoding the token.

When changing the algorithm, its old value must be added to this set. The algorithm specified in algorithm does not have to be part of this set.

This variable is not part of the claim set.

strict_verification: ClassVar[bool] = True¶

If set to True (by default), verifying a token will fail if the token has not been created with the class with which it has been created.

If you want to verify tokens created by third parties (i.e. tokens that have not been created by the application verifying the token), you must set this option to False.

Setting this option to False will also remove the meta claim from created tokens that EasyJWT uses to identify the class with which the token has been created.

audience: Optional[Union[Iterable[str], str]]¶

The audience for which this token is intended. This instance variable is mapped to the registered claim aud.

When verifying a token with an audience claim, the application must identify itself with at least one of the audience values specified in the audience claim. Otherwise, an InvalidAudienceError will be raised. If the application specifies an audience during verification, but the token does not contain an audience claim, an InvalidClaimSetError will be raised.

expiration_date: Optional[datetime.datetime]¶

The date and time at which this token will expire. This instance variable is mapped to the registered claim exp.

If this claim is included in a token and this token is verified after the date has passed, the verification will fail with an ExpiredTokenError error.

Must be given in UTC.

issued_at_date: Optional[datetime.datetime]¶

The date and time at which the token has been created. This instance variable is mapped to the registered claim iat.

This claim will automatically be set in create(). See that method on how to overwrite the value.

When initializing a new object, this claim will be None. With each creation, it will be updated accordingly. When verifying a token and restoring the object, this claim will be set to the value given in the token (if it is included).

Will be given in UTC.

issuer: Optional[str]¶

The issuer of this token. This instance variable is mapped to the registered claim iss.

The issuer of a token can be verified by passing the expected issuer to the verify() method. If the issuer specified in the token does not match the expected one, an InvalidIssuerError error will be raised. If the token does not contain an issuer if one is expected, an InvalidClaimSetError error will be raised.

JWT_ID: Optional[str]¶

A unique identifier for the JWT. This instance variable is mapped to the registered claim jti.

This registered claim is not validated when verifying a token. The processing of this claim is up the application.

not_before_date: Optional[datetime.datetime]¶

The date and time before which this token will not be valid. This instance variable is mapped to the registered claim nbf.

If this claim is included in a token and this token is verified before the date has been reached, the verification will fail with an ImmatureTokenError error.

Must be given in UTC.

subject: Optional[str]¶

The subject of the token. This instance variable is mapped to the registered claim sub.

This registered claim is not validated when verifying a token. The processing of this claim is up to the application.

create(issued_at: Optional[datetime.datetime] = None) → str[source]¶

Create the actual token from the EasyJWT object. Empty optional claims will not be included in the token. Empty non-optional claims will cause a MissingRequiredClaimsError.

Parameters

issued_at – The date and time at which this token was issued. If not given, the current date and time will be used. Must be given in UTC. Defaults to None.

Returns

The token represented by the current state of the object.

Raises

IncompatibleKeyError – If the given key is incompatible with the algorithm used for encoding the token.
MissingRequiredClaimsError – If instance variables that map to non-optional claims in the claim set are empty.

classmethod verify(token: str, key: str, issuer: Optional[str] = None, audience: Optional[Union[Iterable[str], str]] = None) → EasyJWTClass[source]¶

Verify the given JSON Web Token.

Parameters

token – The JWT to verify.
key – The key used for decoding the token. This key must be the same with which the token has been created.
issuer – The issuer of the token to verify.
audience – The audience for which the token is intended.

Returns

The object representing the token. The claim values are set on the corresponding instance variables.

Raises

ExpiredTokenError – If the claim set contains an expiration date claim exp that has passed.
ImmatureTokenError – If the claim set contains a not-before date claim nbf that has not yet been reached.
IncompatibleKeyError – If the given key is incompatible with the algorithm used for decoding the token.
InvalidAudienceError – If the given audience is not specified in the token’s audience claim, or no audience is given when verifying a token with an audience claim, or the given audience is not a string, an iterable, or None.
InvalidClaimSetError – If the claim set does not contain exactly the expected (non-optional) claims.
InvalidClassError – If the claim set is not verified with the class with which the token has been created.
InvalidIssuedAtError – If the claim set contains an issued-at date iat that is not an integer.
InvalidIssuerError – If the token has been issued by a different issuer than given.
InvalidSignatureError – If the token’s signature does not validate the token’s contents.
UnspecifiedClassError – If the claim set does not contain the class with which the token has been created.
UnsupportedAlgorithmError – If the algorithm used for encoding the token is not supported.
VerificationError – If a general error occurred during decoding.

Enumerations¶

This section lists all enumerations defined by EasyJWT.

class Algorithm(value)[source]¶

Bases: enum.Enum

The supported algorithms for cryptographically signing the tokens.

HS256 = 'HS256'¶: HMAC using the SHA-256 hash algorithm.

HS384 = 'HS384'¶: HMAC using the SHA-384 hash algorithm.

HS512 = 'HS512'¶: HMAC using the SHA-512 hash algorithm.

Errors¶

This section lists all error classes defined by EasyJWT.

exception EasyJWTError(message: str)[source]¶

Bases: Exception

A base class for all errors raised by EasyJWT.

Parameters: message – A user-readable description of this error.

Creation Errors¶

This section lists all error classed defined by EasyJWT that may be raised during the creation of a token. Note that some error classes may also listed below Verification Errors.

exception CreationError(message: str)[source]¶

Bases: easyjwt.errors.EasyJWTError

A base class for all errors raised during the creation of a token.

Parameters: message – A user-readable description of this error.

exception IncompatibleKeyError(message: str)[source]¶

Bases: easyjwt.errors.EasyJWTError

Raised if the creation or verification of a token fails because the given key is incompatible with the used algorithm.

Parameters: message – A user-readable description of this error.

exception MissingRequiredClaimsError(missing_claims: Iterable[str])[source]¶

Bases: easyjwt.errors.CreationError

Raised if the creation of a token fails because non-optional claims are empty.

Parameters: missing_claims – The names of claims that are required but empty.

missing_claims: Set[str]¶: A set of the names of claims that are expected but missing in the claim set.

Verification Errors¶

This section lists all error classed defined by EasyJWT that may be raised during the verification of a token. Note that some error classes may also listed below Creation Errors.

exception VerificationError(message: str)[source]¶

Bases: easyjwt.errors.EasyJWTError

A base class for all errors raised during the verification of a token.

Parameters: message – A user-readable description of this error.

exception ExpiredTokenError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the included expiration date has passed.

Parameters: message – A user-readable description of this error.

exception ImmatureTokenError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the included not-before date has not yet been reached.

Parameters: message – A user-readable description of this error.

exception IncompatibleKeyError(message: str)[source]¶

Bases: easyjwt.errors.EasyJWTError

Raised if the creation or verification of a token fails because the given key is incompatible with the used algorithm.

Parameters: message – A user-readable description of this error.

exception InvalidAudienceError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the audience with which the application tries to verify a token is not included in the token’s audience claim, or the audience given in the verify method is not a string, an iterable, or None.

Parameters: message – A user-readable description of this error.

exception InvalidClaimSetError(missing_claims: Optional[Iterable[str]] = None, unexpected_claims: Optional[Iterable[str]] = None)[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the claim set is invalid due to missing or unexpected claims.

Parameters

missing_claims – The names of claims that are expected but missing in the claim set.
unexpected_claims – The names of claims that are given in the claim set but are not specified in the class.

missing_claims: Set[str]¶

A set of the names of claims that are expected but missing in the claim set.

If no missing claims are given, this will be an empty set.

unexpected_claims: Set[str]¶

A set of the names of claims that are given in the claim set but are not specified in the class.

If no unexpected claims are given, this will be an empty set.

exception InvalidClassError(expected_class: str, actual_class: str)[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the EasyJWT class with which it has been created is not the one with which it is being verified.

Parameters

expected_class – The class with which the token is being verified.
actual_class – The class with which the token has been created.

actual_class: str¶: The name of the class with which the token has been created.

expected_class: str¶: The name of the class with which the token has been verified.

exception InvalidIssuedAtError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the issued-at date specified in a token is not an integer.

Parameters: message – A user-readable description of this error.

exception InvalidIssuerError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the given issuer is not the issuer of the token.

Parameters: message – A user-readable description of this error.

exception InvalidSignatureError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the token’s signature does not validate the token’s content.

Parameters: message – A user-readable description of this error.

exception UnspecifiedClassError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the EasyJWT class with which it has been created is not specified in the claim set.

Parameters: message – A user-readable description of this error.

exception UnsupportedAlgorithmError[source]¶

Bases: easyjwt.errors.VerificationError

Raised if the verification of a token fails because the algorithm used for encoding the token is not supported.

Parameters: message – A user-readable description of this error.

Modules¶

This section lists all modules defined by EasyJWT.

restoration¶

Collection of functions converting a claim value to the expected format for the EasyJWT object.

All functions must have the signature (Optional[Any]) -> Optional[Any] as an empty value may be given in the claim.

The association between claims and their restoration functions is defined in the dictionary EasyJWT._claim_restore_methods.

restore_timestamp_to_datetime(timestamp: Optional[int]) → Optional[datetime.datetime][source]¶

Convert a timestamp into a datetime object.

Parameters: timestamp – The timestamp to convert (in UTC).
Returns: The corresponding datetime object (in UTC). None if timestamp is None.

Types¶

This section lists the types defined by EasyJWT.

EasyJWTClass¶

The type of the EasyJWT class, allowing subclasses.

alias of TypeVar(‘EasyJWTClass’)