API¶
Flask-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.
Flask-EasyJWT is a simple wrapper around EasyJWT for easy usage in Flask applications. It provides configuration options via Flask’s application configuration for common settings of all tokens created in a web application.
See the included README file or the documentation for details on how to use Flask-EasyJWT.
Classes¶
This section lists all classes defined by Flask-EasyJWT.
-
class
FlaskEasyJWT
(key: Optional[str] = None)[source]¶ Bases:
easyjwt.easyjwt.EasyJWT
The base class for representing JSON Web Tokens (JWT).
To use a JWT, you have to create a subclass inheriting from
FlaskEasyJWT
. 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 thatFlaskEasyJWT
needs to verify the token). For details, see the documentation of EasyJWT.FlaskEasyJWT
simplifies the usage of EasyJWT in Flask applications by allowing to specify a few common settings in the application’s configuration:The key used for encoding and decoding a token can be specified in the configuration key
EASYJWT_KEY
.The validity of a token can be specified in the configuration key
EASYJWT_TOKEN_VALIDITY
. The expiration date will be set at the time of creation of a token to the current time plus the specified duration (in seconds).
- Parameters
key – If set, the given string will be used to encrypt tokens when they are created. If not given, the key defined in the application’s configuration will be used. Defaults to None.
- Raises
EasyJWTError – If no key is given and there is no key defined in the application’s configuration.
-
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 aMissingRequiredClaimsError
.- 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: Optional[str] = None, issuer: Optional[str] = None, audience: Optional[Union[Iterable[str], str]] = None) → FlaskEasyJWTClass[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. If left empty, the key set in the application’s configuration will be used.
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
EasyJWTError – If no key is given and there is no key defined in the application’s configuration.
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.
-
static
get_validity
() → Optional[datetime.timedelta][source]¶ Get the token’s validity from the configuration of the current Flask application.
The token’s validity is read from the configuration key EASYJWT_TOKEN_VALIDITY. The value can either be a string castable to an integer, an integer (both interpreted in seconds), or a datetime.timedelta object.
This method must be executed within the application context.
- Returns
None if no token validity is defined in the application’s configuration or if the value has a wrong type.
Enumerations¶
This section lists all enumerations defined by Flask-EasyJWT.
Errors¶
This section lists all error classes defined by Flask-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 Flask-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 Flask-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.
Types¶
This section lists the types defined by Flask-EasyJWT.
-
FlaskEasyJWTClass
¶ The type of the
FlaskEasyJWT
class, allowing subclasses.alias of TypeVar(‘FlaskEasyJWTClass’, covariant=True)