API Reference

Module Level Attributes

flask_jwtlib.JWT_ALGO = 'RS256'

The algorithm to use to verify JWTs.

This should be a string recognizable to jwt.decode()’s ‘algorithm’ kwarg.

flask_jwtlib.VERIFICATION_KEY_CACHE_TIMEOUT = 300

How long to hold onto a verification key we get from calling retrieve_verification_key() in seconds.

Note: This value will be ignored if set_permanent_verification_key() has been called.

Functions

flask_jwtlib.set_permanent_verification_key(verification_key)

Sets a permanent verification key

Note: If this function is called retrieve_verification_key() never will be by verification_key()

Parameters:verification_key (str) – The key to always use for verification Returns:None Return type:NoneType

flask_jwtlib.verification_key()

Returns the verification key used for verifying JWTs.

This function includes the machinery for managing the verification key cache, and is how all other functions/decorators which require it retrieve the verification key internally.

Returns:The verification key Return type:str

flask_jwtlib.get_json_token(verify=True)

A wrapper for get_token() which decodes the token and returns the JSON

Parameters:verify (bool) – Whether or not to verify the token, as well as decoding it Returns:The decoded token Return type:dict

flask_jwtlib.is_authenticated()

Returns:Whether or not the current request is authenticated Return type:bool

Callbacks

Functionality may be changed or introduced by registering callbacks to these functions.

flask_jwtlib.retrieve_verification_key()

A callback to refresh the verification key

Useful if the verification key is on a remote source and may be changed periodically.

If implemented, this function should return the verification key as a str or, in the event of failure, raise an exception.

Raises:NotImplemented – if no callback is registered

flask_jwtlib.check_token(token)

Check the token. This function will be called from within the decorators to determine if a token is valid or not.

You should override this function if token validity within your service is determined by anything other than strictly the validity of the token signature, eg: token key values.

For the default implementation see _DEFAULT_CHECK_TOKEN()

Returns:Whether or not the token is valid Return type:bool

flask_jwtlib.get_token()

A callback that should return the encoded token

The default implementation uses only the token retrieval methods specificed in RFC 6750. If you want to extend it override this function with one of your own, optionally calling flask_jwtlib._DEFAULT_GET_TOKEN() in your own implementation

Returns:The token, or None if no token could be retrieved Return type:str or NoneType

flask_jwtlib.requires_authentication_failure_callback()

A callback for when the client doesn’t provide a valid token.

This callback must have a return value.

For the default implementation see _DEFAULT_REQUIRES_AUTHENTICATION_FAILURE_CALLBACK()

Returns:A response

flask_jwtlib.optional_authentication_failure_callback()

A callback for when the client doesn’t provide a token. This callback should not have a return value.

Dumping any (now invalid) tokens out of caches should probably be done here.

For the default implementation see _DEFAULT_OPTIONAL_AUTHENTICATION_FAILURE_CALLBACK()

Decorators

flask_jwtlib.requires_authentication(f)

A decorator for applying to routes where authentication is required.

In the event a user is not authenticated the return value of requires_authentication_failure_callback() will be returned instead of the return value of the route.

In any decorated endpoint, sets the following attributes on flask.g on success:

• authenticated (bool): Whether or not the user is authenticated
• raw_token (str): The encoded token
• json_token (dict): The decoded token as a dict

flask_jwtlib.optional_authentication(f)

A decorator for applying to routes where authentication is optional.

In the event a user is not authenticated optional_authentication_failure_callback() will be called, but the decorated endpoint will still be returned.

In any decorated endpoint, sets the following attributes on flask.g:

• authenticated (bool): Whether or not the user is authenticated
• raw_token (str or None): The encoded token, or None if no token was provided
• json_token (dict or None): The decoded token as a dict, or None if no token was provided.

Default Callback Implementations

These functions are provided as default implementations for callbacks, and should not be overriden in order to change functionality (unless you really know what you’re doing).

Instead, in order to alter callback behavior override the callback function itself, optionally calling the default implementations as provided here if you want to extend, rather than override, the functionality.

flask_jwtlib._DEFAULT_CHECK_TOKEN(token)

The default implementation of the token checking function, exposed as check_token().

Parameters:token (str) – The token as an encoded string. Returns:Whether or not the token is valid Return type:bool

flask_jwtlib._DEFAULT_GET_TOKEN()

The default implementation of retrieving a bearer token from a request, exposed as get_token().

Expects the request to supply the token in one of the three ways specified in RFC 6750:

• via the header
• via a form argument
• via the query string

Returns:The token, or None Return type:str or NoneType

flask_jwtlib._DEFAULT_REQUIRES_AUTHENTICATION_FAILURE_CALLBACK()

The default callback for failing to provide authentication when it is required: Throw a 401. Exposed as requires_authentication_failure_callback().

Returns:A 401 response

flask_jwtlib._DEFAULT_OPTIONAL_AUTHENTICATION_FAILURE_CALLBACK()

The default callback for failing to provide authentication when it is optional: Do nothing. Exposed as optional_authentication_failure_callback().