API Documentation

In here you will find the API for everything exposed in this extension.

Configuring Quart-JWT-Extended

class quart_jwt_extended.JWTManager(app=None)

An object used to hold JWT settings and callback functions for the Quart-JWT-Extended extension.

Instances of JWTManager are not bound to specific apps, so you can create one in the main body of your code and then bind it to your app in a factory function.

__init__(app=None)

Create the JWTManager instance. You can either pass a quart application in directly here to register this extension with the quart app, or call init_app after creating this object (in a factory pattern).

Parameters:

app – A quart application

init_app(app)

Register this extension with the quart app.

Parameters:

app – A quart application

claims_verification_loader(callback)

This decorator sets the callback function that will be called when a protected endpoint is accessed, and will check if the custom claims in the JWT are valid. By default, this callback is not used. The error returned if the claims are invalid can be controlled via the claims_verification_failed_loader() decorator.

HINT: This callback must be a function that takes one argument, which is the custom claims (python dict) present in the JWT, and returns `True` if the claims are valid, or `False` otherwise.

claims_verification_failed_loader(callback)

This decorator sets the callback function that will be called if the claims_verification_loader() callback returns False, indicating that the user claims are not valid. The default implementation will return a 400 status code with the JSON:

{“msg”: “User claims verification failed”}

HINT: This callback must be a function that takes no arguments, and returns a Quart response.

decode_key_loader(callback)

This decorator sets the callback function for getting the JWT decode key and can be used to dynamically choose the appropriate decode key based on token contents.

The default implementation returns the decode key specified by JWT_SECRET_KEY or JWT_PUBLIC_KEY, depending on the signing algorithm.

HINT: The callback function should be a function that takes two arguments, which are the unverified claims and headers of the jwt (dictionaries). The function must return a string which is the decode key in PEM format to verify the token.

encode_key_loader(callback)

This decorator sets the callback function for getting the JWT encode key and can be used to dynamically choose the appropriate encode key based on the token identity.

The default implementation returns the encode key specified by JWT_SECRET_KEY or JWT_PRIVATE_KEY, depending on the signing algorithm.

HINT: The callback function must be a function that takes only one argument, which is the identity as passed into the create_access_token or create_refresh_token functions, and must return a string which is the decode key to verify the token.

expired_token_loader(callback)

This decorator sets the callback function that will be called if an expired JWT attempts to access a protected endpoint. The default implementation will return a 401 status code with the JSON:

{“msg”: “Token has expired”}

HINT: The callback must be a function that takes one argument, which is a dictionary containing the data for the expired token, and and returns a Quart response.

invalid_token_loader(callback)

This decorator sets the callback function that will be called if an invalid JWT attempts to access a protected endpoint. The default implementation will return a 422 status code with the JSON:

{“msg”: “<error description>”}

HINT: The callback must be a function that takes only one argument, which is a string which contains the reason why a token is invalid, and returns a Quart response.

needs_fresh_token_loader(callback)

This decorator sets the callback function that will be called if a valid and non-fresh token attempts to access an endpoint protected with the fresh_jwt_required() decorator. The default implementation will return a 401 status code with the JSON:

{“msg”: “Fresh token required”}

HINT: The callback must be a function that takes no arguments, and returns a Quart response.

revoked_token_loader(callback)

This decorator sets the callback function that will be called if a revoked token attempts to access a protected endpoint. The default implementation will return a 401 status code with the JSON:

{“msg”: “Token has been revoked”}

HINT: The callback must be a function that takes no arguments, and returns a Quart response.

token_in_blacklist_loader(callback)

This decorator sets the callback function that will be called when a protected endpoint is accessed and will check if the JWT has been been revoked. By default, this callback is not used.

HINT: The callback must be a function that takes one argument, which is the decoded JWT (python dictionary), and returns `True` if the token has been blacklisted (or is otherwise considered revoked), or `False` otherwise.

unauthorized_loader(callback)

This decorator sets the callback function that will be called if an no JWT can be found when attempting to access a protected endpoint. The default implementation will return a 401 status code with the JSON:

{“msg”: “<error description>”}

HINT: The callback must be a function that takes only one argument, which is a string which contains the reason why a JWT could not be found, and returns a Quart response.

user_claims_loader(callback)

This decorator sets the callback function for adding custom claims to an access token when create_access_token() is called. By default, no extra user claims will be added to the JWT.

HINT: The callback function must be a function that takes only one argument, which is the object passed into create_access_token(), and returns the custom claims you want included in the access tokens. This returned claims must be JSON serializable.

user_identity_loader(callback)

This decorator sets the callback function for getting the JSON serializable identity out of whatever object is passed into create_access_token() and create_refresh_token(). By default, this will return the unmodified object that is passed in as the identity kwarg to the above functions.

HINT: The callback function must be a function that takes only one argument, which is the object passed into create_access_token() or create_refresh_token(), and returns the JSON serializable identity of this token.

user_loader_callback_loader(callback)

This decorator sets the callback function that will be called to automatically load an object when a protected endpoint is accessed. By default this is not used.

HINT: The callback must take one argument which is the identity JWT accessing the protected endpoint, and it must return any object (which can then be accessed via the current_user LocalProxy in the protected endpoint), or None in the case of a user not being able to be loaded for any reason. If this callback function returns None, the user_loader_error_loader() will be called.

user_loader_error_loader(callback)

This decorator sets the callback function that will be called if None is returned from the user_loader_callback_loader() callback function. The default implementation will return a 401 status code with the JSON:

{“msg”: “Error loading the user <identity>”}

HINT: The callback must be a function that takes one argument, which is the identity of the user who failed to load, and must return a Quart response.

Protected endpoint decorators

quart_jwt_extended.jwt_required(fn)

A decorator to protect a Quart endpoint.

If you decorate an endpoint with this, it will ensure that the requester has a valid access token before allowing the endpoint to be called. This does not check the freshness of the access token.

See also: fresh_jwt_required()

quart_jwt_extended.jwt_refresh_token_required(fn)

A decorator to protect a Quart endpoint.

If you decorate an endpoint with this, it will ensure that the requester has a valid refresh token before allowing the endpoint to be called.

quart_jwt_extended.fresh_jwt_required(fn)

A decorator to protect a Quart endpoint.

If you decorate an endpoint with this, it will ensure that the requester has a valid and fresh access token before allowing the endpoint to be called.

See also: jwt_required()

quart_jwt_extended.jwt_optional(fn)

A decorator to optionally protect a Quart endpoint

If an access token in present in the request, this will call the endpoint with get_jwt_identity() having the identity of the access token. If no access token is present in the request, this endpoint will still be called, but get_jwt_identity() will return None instead.

If there is an invalid access token in the request (expired, tampered with, etc), this will still call the appropriate error handler instead of allowing the endpoint to be called as if there is no access token in the request.

Verify Tokens in Request

These perform the same actions as the protected endpoint decorators, without actually decorating a function. These are very useful if you want to create your own decorators on top of quart jwt extended (such as role_required), or if you want to hook some of this extensions functionality into a quart before_request handler.

async quart_jwt_extended.verify_jwt_in_request()

Ensure that the requester has a valid access token. This does not check the freshness of the access token. Raises an appropiate exception there is no token or if the token is invalid.

async quart_jwt_extended.verify_jwt_in_request_optional()

Optionally check if this request has a valid access token. If an access token in present in the request, get_jwt_identity() will return the identity of the access token. If no access token is present in the request, this simply returns, and get_jwt_identity() will return None instead.

If there is an invalid access token in the request (expired, tampered with, etc), this will still raise the appropiate exception.

async quart_jwt_extended.verify_fresh_jwt_in_request()

Ensure that the requester has a valid and fresh access token. Raises an appropiate exception if there is no token, the token is invalid, or the token is not marked as fresh.

async quart_jwt_extended.verify_jwt_refresh_token_in_request()

Ensure that the requester has a valid refresh token. Raises an appropiate exception if there is no token or the token is invalid.

Utilities

quart_jwt_extended.create_access_token(identity, fresh=False, expires_delta=None, user_claims=None, headers=None)

Create a new access token.

Parameters:

• identity – The identity of this token, which can be any data that is json serializable. It can also be a python object, in which case you can use the user_identity_loader() to define a callback function that will be used to pull a json serializable identity out of the object.

• fresh – If this token should be marked as fresh, and can thus access fresh_jwt_required() endpoints. Defaults to False. This value can also be a datetime.timedelta in which case it will indicate how long this token will be considered fresh.

• expires_delta – A datetime.timedelta for how long this token should last before it expires. Set to False to disable expiration. If this is None, it will use the ‘JWT_ACCESS_TOKEN_EXPIRES` config value (see Configuration Options)

• user_claims – Optional JSON serializable to override user claims.

• headers – Optional, valid dict for specifying additional headers in JWT header section

Returns:

An encoded access token

quart_jwt_extended.create_refresh_token(identity, expires_delta=None, user_claims=None, headers=None)

Creates a new refresh token.

Parameters:

• identity – The identity of this token, which can be any data that is json serializable. It can also be a python object, in which case you can use the user_identity_loader() to define a callback function that will be used to pull a json serializable identity out of the object.

• expires_delta – A datetime.timedelta for how long this token should last before it expires. Set to False to disable expiration. If this is None, it will use the ‘JWT_REFRESH_TOKEN_EXPIRES` config value (see Configuration Options)

• user_claims – Optional JSON serializable to override user claims.

• headers – Optional, valid dict for specifying additional headers in JWT header section

Returns:

An encoded refresh token

quart_jwt_extended.current_user

A LocalProxy for accessing the current user. Roughly equilivant to get_current_user()

quart_jwt_extended.decode_token(encoded_token, csrf_value=None, allow_expired=False)

Returns the decoded token (python dict) from an encoded JWT. This does all the checks to insure that the decoded token is valid before returning it.

Parameters:

• encoded_token – The encoded JWT to decode into a python dict.

• csrf_value – Expected CSRF double submit value (optional)

• allow_expired – Options to ignore exp claim validation in token

Returns:

Dictionary containing contents of the JWT

quart_jwt_extended.get_current_user()

In a protected endpoint, this will return the user object for the JWT that is accessing this endpoint. This is only present if the user_loader_callback_loader() is being used. If the user loader callback is not being used, this will return None.

quart_jwt_extended.get_csrf_token(encoded_token)

Returns the CSRF double submit token from an encoded JWT.

Parameters:

encoded_token – The encoded JWT

Returns:

The CSRF double submit token

quart_jwt_extended.get_jti(encoded_token)

Returns the JTI (unique identifier) of an encoded JWT

Parameters:

encoded_token – The encoded JWT to get the JTI from.

quart_jwt_extended.get_jwt_claims()

In a protected endpoint, this will return the dictionary of custom claims in the JWT that is accessing the endpoint. If no custom user claims are present, an empty dict is returned instead.

quart_jwt_extended.get_jwt_identity()

In a protected endpoint, this will return the identity of the JWT that is accessing this endpoint. If no JWT is present,`None` is returned instead.

quart_jwt_extended.get_raw_jwt()

In a protected endpoint, this will return the python dictionary which has all of the claims of the JWT that is accessing the endpoint. If no JWT is currently present, an empty dict is returned instead.

quart_jwt_extended.set_access_cookies(response, encoded_access_token, max_age=None)

Takes a quart response object, and an encoded access token, and configures the response to set in the access token in a cookie. If JWT_CSRF_IN_COOKIES is True (see Configuration Options), this will also set the CSRF double submit values in a separate cookie.

Parameters:

• response – The Quart response object to set the access cookies in.

• encoded_access_token – The encoded access token to set in the cookies.

• max_age – The max age of the cookie. If this is None, it will use the JWT_SESSION_COOKIE option (see Configuration Options). Otherwise, it will use this as the cookies max-age and the JWT_SESSION_COOKIE option will be ignored. Values should be the number of seconds (as an integer).

quart_jwt_extended.set_refresh_cookies(response, encoded_refresh_token, max_age=None)

Takes a quart response object, and an encoded refresh token, and configures the response to set in the refresh token in a cookie. If JWT_CSRF_IN_COOKIES is True (see Configuration Options), this will also set the CSRF double submit values in a separate cookie.

Parameters:

• response – The Quart response object to set the refresh cookies in.

• encoded_refresh_token – The encoded refresh token to set in the cookies.

• max_age – The max age of the cookie. If this is None, it will use the JWT_SESSION_COOKIE option (see Configuration Options). Otherwise, it will use this as the cookies max-age and the JWT_SESSION_COOKIE option will be ignored. Values should be the number of seconds (as an integer).

quart_jwt_extended.unset_jwt_cookies(response)

Takes a quart response object, and configures it to unset (delete) JWTs stored in cookies.

Parameters:

response – The Quart response object to delete the JWT cookies in.