Skip to content

JWTConfig class

Reference for the JWTConfig class object and how to use it.

Read more about how to use the JWTConfig in your application and leverage the system.

How to import

from esmerald import JWTConfig


Bases: BaseModel

An instance of JWTConfig.

This is a configuration that should be used with a dependency and for that reason you must run first:

$ pip install esmerald[jwt]

This configuration is passed to the CORSMiddleware and enables the middleware.



This following example will build an auth middleware and it will be using the Esmerald contrib version.

You are free to ignore this and build your own.

from esmerald import Esmerald, settings
from esmerald.config.jwt import JWTConfig
from esmerald.contrib.auth.edgy.base_user import AbstractUser

from edgy import Database, Registry

database = Database("sqlite:///db.sqlite")
registry = Registry(database=database)

class User(AbstractUser):
    Inheriting from the the contrib user for Edgy.

    class Meta:
        registry = registry

jwt_config = JWTConfig(

auth_middleware = StarletteMiddleware(
    JWTAuthMiddleware, config=jwt_config, user_model=User

app = Esmerald(middleware=[auth_middleware])

signing_key instance-attribute


The secret used to encode and generate the JWT Token. Having a centralized secret like in the settings would be recommended as it would be the source of truth for any configuration needing a secret.

api_key_header class-attribute instance-attribute

api_key_header = 'X_API_TOKEN'

API Key header for the jwt.

authorization_header class-attribute instance-attribute

authorization_header = 'Authorization'

Authorization header name.

algorithm class-attribute instance-attribute

algorithm = 'HS256'

Algorithm used for the jwt token encoding/decoding.

access_token_lifetime class-attribute instance-attribute

access_token_lifetime = timedelta(minutes=5)

Lifetime of the token after generation.

refresh_token_lifetime class-attribute instance-attribute

refresh_token_lifetime = timedelta(days=1)

Lifetime of the generated refresh token.

auth_header_types class-attribute instance-attribute

auth_header_types = ['Bearer']

Header to be sent with the token value.

jti_claim class-attribute instance-attribute

jti_claim = 'jti'

Used to prevent the JWT from being relayed and relay attacks.

verifying_key class-attribute instance-attribute

verifying_key = ''

Verification key.

leeway class-attribute instance-attribute

leeway = 0

Used for when there is a clock skew times.

sliding_token_lifetime class-attribute instance-attribute

sliding_token_lifetime = timedelta(minutes=5)

A datetime.timedelta object which specifies how long sliding tokens are valid to prove authentication. This timedelta value is added to the current UTC time during token generation to obtain the token's default exp claim value.

sliding_token_refresh_lifetime class-attribute instance-attribute

sliding_token_refresh_lifetime = timedelta(days=1)

A datetime.timedelta object which specifies how long sliding tokens are valid to be refreshed. This timedelta value is added to the current UTC time during token generation to obtain the token's default exp claim value.

user_id_field class-attribute instance-attribute

user_id_field = 'id'

The database field from the user model that will be included in generated tokens to identify users. It is recommended that the value of this setting specifies a field that does not normally change once its initial value is chosen. For example, specifying a username or email field would be a poor choice since an account's username or email might change depending on how account management in a given service is designed. This could allow a new account to be created with an old username while an existing token is still valid which uses that username as a user identifier.

user_id_claim class-attribute instance-attribute

user_id_claim = 'user_id'

The claim in generated tokens which will be used to store user identifiers. For example, a setting value of 'user_id' would mean generated tokens include a user_id claim that contains the user's identifier.

access_token_name class-attribute instance-attribute

access_token_name = 'access_token'

Name of the key for the access token.

refresh_token_name class-attribute instance-attribute

refresh_token_name = 'refresh_token'

Name of the key for the refresh token.