In this article

March 20, 2026

Securing a FastAPI Server with WorkOS AuthKit

Add production-ready authentication to your FastAPI server in under an hour.

Maria Paktiti

March 20, 2026

FastAPI has become one of the most popular Python frameworks for building APIs. It's fast, async-native, generates interactive docs automatically, and has a type system that catches bugs before they hit production. But building an API is only half the job. Once you have endpoints worth protecting, you need an auth layer you can actually trust.

Rolling your own authentication is a common trap. JWT handling, JWKS rotation, session management, secure cookie storage: each piece looks simple in isolation, but the surface area adds up fast and the failure modes are subtle. Most teams are better off delegating that responsibility to a purpose-built identity platform and keeping their application code focused on business logic.

WorkOS is that platform. It's an authentication service that handles the full auth flow: sign-in UI, session management, token issuance, and key rotation. Your FastAPI server connects to it via the WorkOS Python SDK, verifies tokens on incoming requests, and lets AuthKit handle everything else. The result is a secure API without the overhead of building and maintaining an auth system from scratch.

This tutorial walks through the full integration: setting up a FastAPI project, connecting it to WorkOS AuthKit, protecting endpoints with session-based auth, and testing the flow end to end.

What we'll build

We'll build a simple Expense Tracker API. Users can log expenses and retrieve them, but only after authenticating.

The API has three endpoints:

Method	Path	Access
GET	/health	Public Anyone can call it
GET	/expenses	Protected Valid session required
POST	/expenses	Protected Valid session required

Prerequisites

Python 3.10 or later.
A WorkOS account (free for up to 1 million active users, no credit card required).
Basic familiarity with FastAPI.

We'll use uv to manage our project. It's a modern Python package manager written in Rust that replaces pip, virtualenv, and poetry in one tool. Install it with:

  
curl -LsSf https://astral.sh/uv/install.sh | sh

Step 1: Set up the project

Create a new project and navigate into it:

  
uv init expense-tracker
cd expense-tracker
uv venv --python 3.12

Now install our dependencies:

  
uv add fastapi[standard] workos PyJWT[crypto] python-dotenv

Here's what each package does:

fastapi[standard]: FastAPI plus its built-in development server (fastapi dev)
workos: The official WorkOS Python SDK for user management and auth
PyJWT[crypto]: JWT decoding and verification (the [crypto] extra adds RSA/ECDSA support, which WorkOS uses)
python-dotenv: Loads environment variables from a .env file

Step 2: Configure WorkOS

1. Configure your app's endpoints

You need to configure three endpoints:

Redirect URI: This is a callback endpoint that WorkOS will redirect to after a user has authenticated. This endpoint will exchange the authorization code returned by WorkOS for an authenticated User object. We’ll create this endpoint in the next step.
Sign-in endpoint: Sometimes sign-in requests may not begin at your app. For example, some users might bookmark the hosted sign-in page or they might be led directly to the hosted sign-in page when clicking on a password reset link in an email. In these cases, AuthKit will detect when a sign-in request did not originate at your application and redirect to your application’s sign-in endpoint. We’ll create this endpoint in the next step.
Sign-out redirect: The page where users will be redirected when they sign out of your application.

Go to WorkOS dashboard > Redirects and configure these three endpoints.

Screenshot of WorkOS dashboard Redirects page — WorkOS dashboard > Redirects

!!If you have multiple apps, then configure the redirects per app at WorkOS dashboard > Applications.!!

2. Grab your credentials

Grab your API key and client ID from the WorkOS dashboard.

Screenshot of WorkOS dashboard — WorkOS dashboard

Then create a .env file in the root of your project:

  
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
WORKOS_COOKIE_PASSWORD="your-secure-32-character-password-here"

WORKOS_COOKIE_PASSWORD is used to encrypt cookies and must be at least 32 characters long. You can generate a secure password by using the 1Password generator or the openssl library via the command line:

  
openssl rand -base64 32

Add .env to your .gitignore, never commit this file:

  
echo ".env" >> .gitignore

Step 3: Build the API

Create a main.py file in the project root. We'll build it up piece by piece.

Base setup

  
# main.py

import os
import jwt
import json
from functools import wraps
from typing import Optional

from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException, Request, Depends
from fastapi.responses import RedirectResponse, JSONResponse
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from pydantic import BaseModel
from workos import WorkOSClient

load_dotenv()

app = FastAPI(title="Expense Tracker API")

workos = WorkOSClient(
    api_key=os.getenv("WORKOS_API_KEY"),
    client_id=os.getenv("WORKOS_CLIENT_ID"),
)

COOKIE_PASSWORD = os.getenv("WORKOS_COOKIE_PASSWORD")
CLIENT_ID = os.getenv("WORKOS_CLIENT_ID")

We're importing FastAPI's HTTPBearer class, which handles extracting the Authorization: Bearer <token> header automatically. The WorkOS client is initialized once at startup and reused across all requests.

Define the expense model

  
# In-memory store for this tutorial — swap for a real DB in production
expense_db: list[dict] = []

class Expense(BaseModel):
    description: str
    amount: float
    category: str

FastAPI uses Pydantic models for request body validation. If someone sends a malformed request (missing a field, wrong type), FastAPI returns a descriptive 422 error automatically so we don't need to write any validation code.

Add the public endpoint

  
@app.get("/health")
def health_check():
    """Public endpoint — no auth required."""
    return {"status": "ok", "service": "expense-tracker"}

This endpoint is fully open. Good for load balancer health checks or a quick sanity test that the server is running.

Add the WorkOS auth endpoints

Before we protect our expense endpoints, we need to give users a way to sign in. AuthKit provides a hosted UI that handles sign-up, sign-in, password reset, and MFA out of the box; you just redirect to it.

  
@app.get("/login")
def login():
    """Redirect to WorkOS AuthKit to sign in."""
    authorization_url = workos.user_management.get_authorization_url(
        provider="authkit",
        redirect_uri="http://localhost:8000/callback",
    )
    return RedirectResponse(url=authorization_url)


@app.get("/callback")
def callback(request: Request, code: str):
    """
    WorkOS redirects here after authentication.
    Exchange the authorization code for a user session.
    """
    try:
        auth_response = workos.user_management.authenticate_with_code(
            code=code,
            session={"seal_session": True, "cookie_password": COOKIE_PASSWORD},
        )

        response = RedirectResponse(url="/expenses")
        response.set_cookie(
            "wos_session",
            auth_response.sealed_session,
            secure=False,   # set to True in production (requires HTTPS)
            httponly=True,  # prevents JavaScript from accessing the cookie
            samesite="lax",
        )
        return response

    except Exception as e:
        raise HTTPException(status_code=401, detail=f"Authentication failed: {str(e)}")


@app.get("/logout")
def logout(request: Request):
    """End the user's session."""
    sealed_session = request.cookies.get("wos_session")
    if not sealed_session:
        return RedirectResponse(url="/")

    session = workos.user_management.load_sealed_session(
        sealed_session=sealed_session,
        cookie_password=COOKIE_PASSWORD,
    )
    logout_url = session.get_logout_url()

    response = RedirectResponse(url=logout_url)
    response.delete_cookie("wos_session")
    return response

A few things worth noting here:

‍The authorization code flow: WorkOS redirects the user to AuthKit's hosted sign-in page. When the user successfully authenticates, WorkOS redirects back to your /callback with a short-lived code parameter. Your server exchanges that code for a session. This is the standard OAuth 2.0 authorization code flow.‍
Sealed sessions: WorkOS encrypts the session data (including the refresh token) before you store it in a cookie. This means even if someone reads the cookie value, they can't extract the refresh token without your COOKIE_PASSWORD. It's the same concept as encrypted session cookies in frameworks like Rails or Django.‍
httponly=True: This flag prevents JavaScript running in the browser from reading the cookie. It's a simple but effective defense against XSS attacks stealing session cookies.

Add the protected endpoints

Now for the interesting part. We need to verify the session on every request to a protected endpoint. Let's write a dependency that does this:

  
def get_current_user(request: Request) -> dict:
    """
    FastAPI dependency that verifies the WorkOS session.
    Returns the authenticated user or raises a 401.
    """
    sealed_session = request.cookies.get("wos_session")

    if not sealed_session:
        raise HTTPException(
            status_code=401,
            detail="Not authenticated. Visit /login to sign in.",
        )

    try:
        session = workos.user_management.load_sealed_session(
            sealed_session=sealed_session,
            cookie_password=COOKIE_PASSWORD,
        )
        auth_response = session.authenticate()

        if not auth_response.authenticated:
            raise HTTPException(status_code=401, detail="Session expired or invalid.")

        return {
            "user_id": auth_response.user.id,
            "email": auth_response.user.email,
            "first_name": auth_response.user.first_name,
        }

    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=401, detail=f"Could not validate session: {str(e)}")

This is a FastAPI dependency. By passing it to an endpoint via Depends(), FastAPI automatically runs it before the endpoint handler. If it raises an HTTPException, FastAPI returns that error response and never calls the endpoint. If it returns successfully, the returned value is injected into the endpoint as a parameter.

Now add the protected endpoints:

  
@app.get("/expenses")
def get_expenses(current_user: dict = Depends(get_current_user)):
    """
    Protected: Return expenses for the authenticated user.
    """
    user_expenses = [
        e for e in expense_db if e["user_id"] == current_user["user_id"]
    ]
    return {
        "user": current_user["email"],
        "expenses": user_expenses,
        "total": sum(e["amount"] for e in user_expenses),
    }


@app.post("/expenses", status_code=201)
def create_expense(expense: Expense, current_user: dict = Depends(get_current_user)):
    """
    Protected: Add a new expense for the authenticated user.
    """
    new_expense = {
        "id": len(expense_db) + 1,
        "user_id": current_user["user_id"],
        "description": expense.description,
        "amount": expense.amount,
        "category": expense.category,
    }
    expense_db.append(new_expense)
    return {"message": "Expense recorded", "expense": new_expense}

Notice that both endpoints have current_user: dict = Depends(get_current_user) in their signature. That single line is all it takes to lock down an endpoint, FastAPI's dependency injection handles the rest.

Step 4: Run It

Start the development server:

  
uv run fastapi dev main.py

FastAPI generates interactive API docs automatically. Open http://localhost:8000/docs to see them. You can explore every endpoint, see the request/response schemas, and try requests directly in the browser.

Test the public endpoint:

  
curl http://localhost:8000/health
# {"status":"ok","service":"expense-tracker"}

Test the protected endpoints:

  
curl http://localhost:8000/expenses
# {"detail":"Not authenticated. Visit /login to sign in."}

Now, visit http://localhost:8000/login in your browser. You'll be redirected to WorkOS AuthKit's hosted sign-in page. Create an account or sign in, and you'll be redirected back to /expenses with a session cookie set.

Now your browser is authenticated. If you test /expenses again from your browser, you'll see an empty expense list (you haven't added any yet). Try creating one:

  
curl -X POST http://localhost:8000/expenses \
  -H "Content-Type: application/json" \
  -b "wos_session=<your_session_cookie>" \
  -d '{"description": "Team lunch", "amount": 47.50, "category": "meals"}'

Then, fetch expenses again:

  
uv run fastapi dev main.py

What WorkOS handles for you

It's worth pausing to appreciate what you didn't have to build:

The sign-in UI (email/password forms, social login buttons, error states).
Password hashing and storage (bcrypt, salting, secure comparison).
Email verification flows (sending verification emails, handling tokens).
Session token signing and rotation (JWKS, key rotation, refresh token management).
Cookie encryption (the sealed session is securely encrypted before it ever touches the browser).

For a production app you'd also get MFA, social login (Google, GitHub, etc.), and, when you're ready to sell to enterprises ,SSO with SAML and OIDC, all without changing your FastAPI code.

What's next

This tutorial covered the human authentication case: a user signs in via a browser and your API validates their session on each request. WorkOS supports several other auth scenarios that build naturally on what you've set up here:

Expose your API as MCP tools for AI agents: If you want AI clients like Claude or Cursor to call your API on a user's behalf, WorkOS AuthKit is a spec-compliant OAuth authorization server that MCP clients already know how to talk to. You'll need to add JWT verification on incoming requests and a couple of OAuth discovery endpoints. Your existing business logic endpoints stay unchanged. See the WorkOS MCP docs for the full integration guide.
Machine-to-machine auth: When another service needs to call your API without a browser or a human in the loop, WorkOS supports M2M authentication via client credentials. See the M2M documentation.
Enterprise SSO: When your B2B customers need to authenticate via their own identity provider (Okta, Azure AD, Google Workspace, and others) WorkOS handles the SAML and OIDC plumbing. No code changes are required on your FastAPI server; you configure the provider once (or ask your customer to configure their own provider using the Admin Portal) and the existing auth flow works as-is.

We will follow up with more tutorials for these use cases soon.

Full code

The complete main.py:

  
# main.py

import os
from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException, Request, Depends
from fastapi.responses import RedirectResponse
from pydantic import BaseModel
from workos import WorkOSClient

load_dotenv()

app = FastAPI(title="Expense Tracker API")

workos = WorkOSClient(
    api_key=os.getenv("WORKOS_API_KEY"),
    client_id=os.getenv("WORKOS_CLIENT_ID"),
)

COOKIE_PASSWORD = os.getenv("WORKOS_COOKIE_PASSWORD")

# In-memory store — swap for a real DB in production
expense_db: list[dict] = []


class Expense(BaseModel):
    description: str
    amount: float
    category: str


# --- Auth endpoints ---

@app.get("/login")
def login():
    authorization_url = workos.user_management.get_authorization_url(
        provider="authkit",
        redirect_uri="http://localhost:8000/callback",
    )
    return RedirectResponse(url=authorization_url)


@app.get("/callback")
def callback(request: Request, code: str):
    try:
        auth_response = workos.user_management.authenticate_with_code(
            code=code,
            session={"seal_session": True, "cookie_password": COOKIE_PASSWORD},
        )
        response = RedirectResponse(url="/expenses")
        response.set_cookie(
            "wos_session",
            auth_response.sealed_session,
            secure=False,
            httponly=True,
            samesite="lax",
        )
        return response
    except Exception as e:
        raise HTTPException(status_code=401, detail=f"Authentication failed: {str(e)}")


@app.get("/logout")
def logout(request: Request):
    sealed_session = request.cookies.get("wos_session")
    if not sealed_session:
        return RedirectResponse(url="/")
    session = workos.user_management.load_sealed_session(
        sealed_session=sealed_session,
        cookie_password=COOKIE_PASSWORD,
    )
    response = RedirectResponse(url=session.get_logout_url())
    response.delete_cookie("wos_session")
    return response


# --- Dependency ---

def get_current_user(request: Request) -> dict:
    sealed_session = request.cookies.get("wos_session")
    if not sealed_session:
        raise HTTPException(status_code=401, detail="Not authenticated. Visit /login to sign in.")
    try:
        session = workos.user_management.load_sealed_session(
            sealed_session=sealed_session,
            cookie_password=COOKIE_PASSWORD,
        )
        auth_response = session.authenticate()
        if not auth_response.authenticated:
            raise HTTPException(status_code=401, detail="Session expired or invalid.")
        return {
            "user_id": auth_response.user.id,
            "email": auth_response.user.email,
            "first_name": auth_response.user.first_name,
        }
    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=401, detail=f"Could not validate session: {str(e)}")


# --- Protected endpoints ---

@app.get("/health")
def health_check():
    return {"status": "ok", "service": "expense-tracker"}


@app.get("/expenses")
def get_expenses(current_user: dict = Depends(get_current_user)):
    user_expenses = [e for e in expense_db if e["user_id"] == current_user["user_id"]]
    return {
        "user": current_user["email"],
        "expenses": user_expenses,
        "total": sum(e["amount"] for e in user_expenses),
    }


@app.post("/expenses", status_code=201)
def create_expense(expense: Expense, current_user: dict = Depends(get_current_user)):
    new_expense = {
        "id": len(expense_db) + 1,
        "user_id": current_user["user_id"],
        "description": expense.description,
        "amount": expense.amount,
        "category": expense.category,
    }
    expense_db.append(new_expense)
    return {"message": "Expense recorded", "expense": new_expense}

We’re hiring

Our global team is growing and we’re hiring all types of roles.

View open roles

About us

WorkOS builds developer tools for quickly adding enterprise features to applications.

Learn more