Skip to content


JWT extends for JSON Web Token and it can be used with any middleware at your desire that implements the BaseAuthMiddleware.


More information about JWT here.


Esmerald uses python-jose and passlib for this JWT integration. You can install by running:

$ pip install esmerald[jwt]

JWTConfig and application

To use the JWTConfig with a middleware.

from myapp.models import User
from starlette.middleware import Middleware as StarletteMiddleware

from esmerald import Esmerald, settings
from esmerald.config.jwt import JWTConfig
from esmerald.contrib.auth.tortoise.middleware import JWTAuthMiddleware

jwt_config = JWTConfig(

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

app = Esmerald(middleware=[auth_middleware])


The example uses a supported JWTAuthMiddleware from Esmerald with Saffier ORM.


All the parameters and defaults are available in the JWTConfig Reference.

JWTConfig and application settings

The JWTConfig can be done directly via application instantiation but also via settings.

from typing import TYPE_CHECKING, List

from starlette.middleware import Middleware as StarletteMiddleware

from esmerald import EsmeraldAPISettings
from esmerald.config.jwt import JWTConfig
from esmerald.contrib.auth.saffier.middleware import JWTAuthMiddleware
from esmerald.utils.module_loading import import_string

    from esmerald.types import Middleware

class CustomSettings(EsmeraldAPISettings):
    def jwt_config(self) -> JWTConfig:
        A JWT object configuration to be passed to the application middleware
        return JWTConfig(signing_key=self.secret_key, auth_header_types=["Bearer", "Token"])

    def middleware(self) -> List["Middleware"]:
        Initial middlewares to be loaded on startup of the application.
        return [

This will make sure you keep the settings clean, separated and without a bloated Esmerald instance.

Token model

Esmerald offers a pretty standard Token object that allows you to generate and decode tokens at ease.

from import Token

token = Token(exp=..., iat=..., sub=...)

The parameters are pretty standard from Python JOSE so you can feel confortable with.

Generate a Token (encode)

The token offers simple and standard operations to interact with python-jose.

from import Token
from esmerald.conf import settings

# Create the token model
token = Token(exp=..., iat=..., sub=...)

# Generate the JWT token
jwt_token = Token.encode(key=settings.secret_key, algorithm="HS256", **claims)

Decode a Token (encode)

The same decoding functionality is also provided.

from import Token
from esmerald.conf import settings

# Decodes the JWT token
jwt_token = Token.decode(token=..., key=settings.secret_key, algorithms=["HS256"])

The Token.decode returns a Token object.


This functionality relies heavily on python-jose but it is not mandatory to use it in any way. You are free to use any library that suits your unique needs. Esmerald only offers some examples and alternatives.