Install Auth SDK

Installation

Install the Wristband Auth SDK using your preferred package manager CLI:

pip install wristband-fastapi-auth

poetry add wristband-fastapi-auth

pipenv install wristband-fastapi-auth

Configuration

Prerequisites

Before you can configure the SDK, you'll need to make sure you have the following values:

• WRISTBAND_APPLICATION_VANITY_DOMAIN
• WRISTBAND_CLIENT_ID
• WRISTBAND_CLIENT_SECRET

If you went through the Set Up a Wristband Application guide, you should have been presented with these three values after the application was provisioned. If you don't have the above values on hand, you can retrieve them from the Wristband dashboard by following the steps in this guide.

Configure the SDK

Create a WristbandAuth instance in your FastAPI project's source root (e.g., src/auth/wristband.py) and configure its AuthConfig properties with your application's values.

⚙️

Disabling Secure Cookies in Local Development

By default, WristbandAuth creates secure cookies (for tracking login state), meaning they are only sent over HTTPS connections. Most browsers make an exception for localhost and allow secure cookies to be sent over HTTP (e.g., http://localhost). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even for localhost.

If you need to disable the secure cookies for local development, set dangerously_disable_secure_cookies=True in AuthConfig. However, be sure to re-enable secure cookies before deploying to production.

# src/auth/wristband.py
from wristband_fastapi_auth import WristbandAuth, AuthConfig

# Initialize Wristband FastAPI Auth SDK
wristband_auth: WristbandAuth = WristbandAuth(
    AuthConfig(
        client_id="<WRISTBAND_CLIENT_ID>",
        client_secret="<WRISTBAND_CLIENT_SECRET>",
        wristband_application_vanity_domain="<WRISTBAND_APPLICATION_VANITY_DOMAIN>",
    )
)

# src/auth/wristband.py
from wristband_fastapi_auth import WristbandAuth, AuthConfig

# Initialize Wristband FastAPI Auth SDK
wristband_auth: WristbandAuth = WristbandAuth(
    AuthConfig(
        client_id="<WRISTBAND_CLIENT_ID>",
        client_secret="<WRISTBAND_CLIENT_SECRET>",
        wristband_application_vanity_domain="<WRISTBAND_APPLICATION_VANITY_DOMAIN>",
        dangerously_disable_secure_cookies=True,
    )
)

Add Auth Dependency

You’ll also need to create an auth dependency to verify that incoming requests have a valid session. You can do this using the WristbandAuth.create_session_auth_dependency() method. Later, you'll use this dependency to protect API routes that require authentication.

After adding the auth dependency, the file should look like the following:

# src/auth/wristband.py
from wristband_fastapi_auth import WristbandAuth, AuthConfig

# Initialize Wristband FastAPI Auth SDK
wristband_auth: WristbandAuth = WristbandAuth(
    AuthConfig(
        client_id="<WRISTBAND_CLIENT_ID>",
        client_secret="<WRISTBAND_CLIENT_SECRET>",
        wristband_application_vanity_domain="<WRISTBAND_APPLICATION_VANITY_DOMAIN>",
    )
)

# Create an auth dependency that verifies a request has a valid session.
require_session_auth = wristband_auth.create_session_auth_dependency()

# Explicitly define what can be imported in your project
__all__ = ["require_session_auth", "wristband_auth"]