Skip to main content

Flask-Login like package for FastAPI

Project description


CI PyPI - Python Version PyPI License

FastAPI-Login tries to provide similar functionality as Flask-Login does.


In-depth documentation can be found at

Some examples can be found here.


pip install fastapi-login


To begin we have to setup our FastAPI app:

from fastapi import FastAPI

SECRET = 'your-secret-key'

app = FastAPI()

To obtain a suitable secret key you can run import os; print(os.urandom(24).hex()).

Now we can import and setup the LoginManager, which will handle the process of encoding and decoding our Json Web Tokens.

from fastapi_login import LoginManager

manager = LoginManager(SECRET, token_url='/auth/token')

For the example we will use a dictionary to represent our user database. In your application this could also be a real database like sqlite or Postgres. It does not matter as you have to provide the function which retrieves the user.

fake_db = {'johndoe@e.mail': {'password': 'hunter2'}}

Now we have to provide the LoginManager with a way to load our user. The user_loader callback should either return your user object or None

def load_user(email: str):  # could also be an asynchronous function
    user = fake_db.get(email)
    return user

Now we have to define a way to let the user login in our app. Therefore we will create a new route:

from fastapi import Depends
from import OAuth2PasswordRequestForm
from fastapi_login.exceptions import InvalidCredentialsException

# the python-multipart package is required to use the OAuth2PasswordRequestForm'/auth/token')
def login(data: OAuth2PasswordRequestForm = Depends()):
    email = data.username
    password = data.password

    user = load_user(email)  # we are using the same function to retrieve the user
    if not user:
        raise InvalidCredentialsException  # you can also use your own HTTPException
    elif password != user['password']:
        raise InvalidCredentialsException

    access_token = manager.create_access_token(
    return {'access_token': access_token, 'token_type': 'bearer'}

Now whenever you want your user to be logged in to use a route, you can simply use your LoginManager instance as a dependency.

def protected_route(user=Depends(manager)):

If you also want to handle a not authenticated error, you can add your own subclass of Exception to the LoginManager.

from starlette.responses import RedirectResponse

class NotAuthenticatedException(Exception):

# these two argument are mandatory
def exc_handler(request, exc):
    return RedirectResponse(url='/login')

manager = LoginManager(..., not_authenticated_exception=NotAuthenticatedException)
# You also have to add an exception handler to your app instance
app.add_exception_handler(NotAuthenticatedException, exc_handler)

To change the expiration date of the token use the expires_delta argument of the create_access_token method with a timedelta. The default is set 15 min. Please be aware that setting a long expiry date is not considered a good practice as it would allow an attacker with the token to use your application as long as he wants.

from datetime import timedelta

data = dict(

# expires after 15 min
token = manager.create_access_token(
# expires after 12 hours
long_token = manager.create_access_token(
    data=data, expires=timedelta(hours=12)

Usage with cookies

Instead of checking the header for the token. fastapi-login also support access using cookies.

from fastapi_login import LoginManager

manager = LoginManager(SECRET, token_url='/auth/token', use_cookie=True)

Now the manager will check the requests cookies the headers for the access token. The name of the cookie can be set using manager.cookie_name. If you only want to check the requests cookies you can turn the headers off using the use_header argument

For convenience the LoginManager also includes the set_cookie method which sets the cookie to your response, with the recommended HTTPOnly flag and the manager.cookie_name as the key.

from fastapi import Depends
from starlette.responses import Response

def auth(response: Response, user=Depends(manager)):
    token = manager.create_access_token(
    manager.set_cookie(response, token)
    return response

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fastapi_login-1.10.1.tar.gz (10.6 kB view hashes)

Uploaded Source

Built Distribution

fastapi_login-1.10.1-py3-none-any.whl (10.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page