Add Auth Endpoints

To implement login and logout flows with Wristband, you'll need to use the Wristband SDK to create four endpoints in your application:

Login Endpoint
Callback Endpoint
Logout Endpoint
Session Endpoint

Login Endpoint

The Login Endpoint is responsible for initiating login requests to Wristband. The code within the Login Endpoint constructs the Wristband authorization request and then redirects to Wristband's Authorize Endpoint. After redirecting to Wristband's Authorize Endpoint, the user will then be directed to Wristband's hosted login page, where they can complete the login process.

Below is a code snippet showing how to use Wristband's SDK to implement the Login Endpoint within your FastAPI application.

# src/routes/auth_routes.py
from fastapi import APIRouter, Request, Response
from wristband.fastapi_auth import (
   CallbackData, CallbackResult, CallbackResultType, LogoutConfig, SessionResponse
)
from auth.wristband import wristband_auth

router = APIRouter()

# Login Endpoint - The path can be any value you prefer, but it must match 
# your Wristband application's configured login URL path and the SDK loginUrl path.
@router.get('/login')
async def login(request: Request) -> Response:
    # Call the Wristband login() method which will generate the Response that should
    # be used to redirect to Wristband's hosted login page.
    return await wristband_auth.login(request)

...

Callback Endpoint

After a user has successfully authenticated, Wristband will redirect to your application's Callback Endpoint. Calling the wristband_auth.callback function will return a CallbackResult object containing the user's tokens and claims. We can use these tokens and claims to create the user's session by calling the request.state.session.from_callback() function.

Below is a code snippet showing how to use Wristband's SDK to implement the Callback Endpoint within your FastAPI application.

# src/routes/auth_routes.py (continued)

# ...

# Callback Endpoint - The path can be any value you prefer, but it must match 
# the path of your OAuth2 Client callback URL and the SDK redirectUri path.
@router.get('/callback')
async def callback(request: Request) -> Response:
    # Call the Wristband callback() method to check if the user
    # successfully authenticated.  If the user did authenticate successfully, 
    # the user's tokens and claims can be retrieved from the `callback_result`.
    callback_result: CallbackResult = await wristband_auth.callback(request)

    # For some edge cases, such as if an invalid grant was passed to the token
    # API, the SDK will return a redirect URL. Your code should redirect to it
    # in order to restart the login flow.
    if callback_result.type == CallbackResultType.REDIRECT_REQUIRED:
        return await wristband_auth.create_callback_response(
            request,
            callback_result.redirect_url,
        )
    
    # Create a session for the authenticated user in FastAPI.
    # (from_callback() also supports an optional `custom_fields` arg, if needed)
    request.state.session.from_callback(callback_result.callback_data)

    # Once the Callback Endpoint has completed, redirect to your app's
    # default return URL (typically your app's home page) or to an explicit
    # return URL, if one was specified in the original login request.
    redirect_url = callback_result.callback_data.return_url or "<replace_with_default_return_url>"
    return await wristband_auth.create_callback_response(request, redirect_url)

...

Logout Endpoint

When a user logs out of your application, you need to ensure that all authenticated state associated with the user is cleaned up. The Logout Endpoint will invalidate the user's session and revoke their refresh token (assuming the session contains a refresh token).

Below is a code snippet showing how to use Wristband's SDK to implement the Logout Endpoint within your FastAPI application.

# src/routes/auth_routes.py (continued)

...

# Logout Endpoint - The path can be any value you prefer.
@router.get('/logout')
async def logout(request: Request) -> Response:
    # Get all necessary session data needed to perform logout
    logout_config = LogoutConfig(
        refresh_token=request.state.session.refresh_token,
        tenant_custom_domain=request.state.session.tenant_custom_domain,
        tenant_name=request.state.session.tenant_name,
    )

    # Delete the session in FastAPI.
    request.state.session.clear()

    # Call the Wristband logout() method and use the returned Response to
    # redirect to Wristband's Logout Endpoint.  This will delete Wristband's 
    # session associated to the authenticated user.  When Wristband is done
    # logging out the user it will redirect back to your application's login 
    # URL or to the explicitly provided redirect URL, if provided.
    return await wristband_auth.logout(request, logout_config)

...

Session Endpoint

The Session Endpoint will check that the incoming request has a valid session, and, if so, it will return a response containing the user's session data. The Session Endpoint serves two primary purposes:

It provides a way for the frontend to check whether the user has a valid session.
It allows the frontend to access the user's session data so it can be utilized in the browser.

Since this guide uses a React frontend, we'll structure the response to match what the React Client Auth SDK expects (which will be covered in the next section of this guide).

At a minimum, the response should include userId and tenantId by calling request.state.session.get_session_response().

# src/routes/auth_routes.py (continued)

...

# Session Endpoint
@router.get("/session")
async def get_session(request: Request) -> SessionResponse:
    # If needed, you can make additional API calls to gather other session 
    # data you might want to return to your frontend. Then you could pass
    # pass that to the `metadata` argument of get_session_response().
    # For now, return only the essentials: userId and tenantId.
    return request.state.session.get_session_response()

Map Auth Endpoints

After implementing the auth endpoints, make sure to include them in your main FastAPI application in your main.py file.

# src/main.py
from fastapi import FastAPI
from wristband.fastapi_auth import SessionMiddleware
from routes.auth_routes import router as auth_router

def create_app() -> FastAPI:
    app = FastAPI()

    app.add_middleware(SessionMiddleware, secret_key="<your-generated-pw>")

    # NEW: Include auth routes - path prefix can be whatever you prefer
    # but should match your Wristband configurations.
    app.include_router(auth_router, prefix="/api/auth")

    # Your other application setup...

Register Your Login Endpoint and Callback Endpoint With Wristband

For several authentication flows, Wristband will need to redirect to your application's Login Endpoint and Callback Endpoint. Therefore, we need to inform Wristband of the URLs for these two endpoints. To do that, we'll need to update the following two fields within the Wristband dashboard:

Application Login URL
Client Redirect URIs

In the sections below, we'll go over how to update these two fields.

Updating the Application Login URL

To update the Application Login URL, follow these steps.

From the Dashboard Home Page, select the appropriate application.

Next, on the Application Settings page, locate the Login URL field and set its value to the URL of your application's Login Endpoint. When you are finished, click the "Save" button.

Updating the Client Redirect URIs

To update the Client Redirect URIs, follow these steps.

Select "OAuth2 Clients" from the left navigation bar, then select the client whose ID matches the client ID that was registered with the SDK.

On the Edit Client page, navigate to the Redirect URIs section and click the "Add+" button. Then enter the URL of your application's Callback Endpoint. When you are finished, click the "Save" button.