Quick start guide

In this guide we add login and a small authenticated response. Every return route runs the same authentication setup.

1. Install the package

Use Python 3.10 or later:

pip install 'authwave[flask]'

2. Register the application

Create a deployment in the provider and configure its client return URI. Set the complete client key in AUTHWAVE_CLIENT_KEY. The final underscore separates deployment ID from the raw 32-byte secret. Keep the value unchanged on the server, outside public files and version control.

For this example configure http://localhost:3000/ as the client return URI.

3. Create the shared setup

Create app.py:

import os
from flask import Flask, request
from authwave.integrations.flask import authwave_handler
from authwave.runtime import MemorySessionStore, SessionOptions

app = Flask(__name__)
options = SessionOptions(MemorySessionStore(), secure_cookie=False)  # Local HTTP only.

@app.route('/')
@app.route('/login')
@app.route('/logout')
@authwave_handler(options, client_key=os.environ['AUTHWAVE_CLIENT_KEY'])
def index(auth):
    if request.path == '/login':
        auth.set_return_uri('/')
        auth.login()
    if request.path == '/logout':
        auth.logout('/')
    return {'id': auth.get_auth_user().id, 'email': auth.get_auth_user().email} if auth.is_logged_in() else {'login': '/login'}

if __name__ == '__main__':
    app.run(port=3000)

Run python app.py, then visit http://localhost:3000/.

The example uses a development memory store and local HTTP cookies. Production applications use HTTPS and a shared persistent store. secure_cookie defaults to True.

4. Add a login endpoint

The /login route requests / as the return destination and starts authentication. The return route uses the same store and authentication setup, allowing it to process the provider's response before rendering content.

The decorator catches redirect signals and saves the session before sending the response. An already logged-in login call returns normally.

5. Show the visitor's state

The home route returns the authenticated ID and email, or the login route when signed out. JSON keeps these examples independent of HTML rendering. Escape user values when rendering HTML.

Visit /login, complete authentication, and follow the provider return and cleanup redirect. Visit /logout to clear local authentication and the provider session.

Django

Install pip install 'authwave[django]'. Wrap login, logout and callback views with authwave.integrations.django.authwave_handler:

@authwave_handler(options, client_key=client_key)
def members(request):
    auth = request.authwave
    if not auth.is_logged_in():
        auth.login()
    return JsonResponse({'id': auth.get_auth_user().id})

Use the same SessionOptions and store across views. The decorator manages its own opaque session cookie; it does not require Django's session middleware.

FastAPI

Install pip install 'authwave[fastapi]' uvicorn. Add the middleware and read request.state.authwave:

from authwave.integrations.fastapi import AuthwaveMiddleware
app.add_middleware(AuthwaveMiddleware, session_options=options, client_key=client_key)

@app.get('/members')
def members(request: Request):
    auth = request.state.authwave
    if not auth.is_logged_in():
        auth.login()
    return {'id': auth.get_auth_user().id}

Run using uvicorn app:app --port 3000. Use a synchronous endpoint when it calls synchronous storage or callbacks. The middleware runs session loading and constructor callbacks in worker threads.

WSGI and ASGI

AuthwaveWSGI(app, options, client_key=...) exposes the authenticator as environ['authwave.auth']. AuthwaveASGI(app, options, client_key=...) exposes it as request.state.authwave. Import these from authwave.integrations.wsgi and authwave.integrations.asgi. Both wrappers buffer HTTP responses and save before output. The repository's examples directory contains runnable framework applications.

---

Next, see Working with the authenticated user.