# How the Password Authentication Middleware Protects API Endpoints in Open Notebook > Discover how Open Notebook's password authentication middleware automatically protects API endpoints using a custom FastAPI middleware and shared-secret Bearer tokens. Learn more today. - Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook) - Tags: how-to-guide - Published: 2026-06-22 --- **Open Notebook uses a shared-secret Bearer token system through a custom FastAPI middleware that automatically gates every API endpoint without requiring individual route decorators.** The `lfnovo/open-notebook` repository secures its FastAPI backend using a lightweight yet effective password authentication middleware. This custom `PasswordAuthMiddleware` ensures that all HTTP requests—whether accessing notebooks, sources, or search endpoints—must present a valid shared secret before reaching business logic. ## Architecture of the Password Authentication Middleware ### Core Implementation in api/auth.py The middleware class is defined in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py). On initialization, it reads the `OPEN_NOTEBOOK_PASSWORD` environment variable, falling back to a hard-coded default if the variable is unset. This secret is stored as an instance attribute for subsequent request validation. ### Request Interception and Validation The `dispatch` method processes every incoming HTTP request before it reaches any router. It performs the following steps: 1. Extracts the `Authorization` header from the incoming request. 2. Validates that the header follows the `Bearer ` format. 3. Compares the provided password against the stored secret. 4. Returns a **401 Unauthorized** response with `{"detail": "Invalid password"}` if validation fails. 5. Passes the request to the next handler if the token matches. ## Global Protection via Middleware Stack In [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py), the middleware is registered at the application level before any routers are mounted: ```python # api/main.py from fastapi import FastAPI from .auth import PasswordAuthMiddleware app = FastAPI() app.add_middleware(PasswordAuthMiddleware) # Protects every endpoint ``` Because the middleware sits at the top of the FastAPI stack, it automatically protects all routes—including notebook, source, search, and transformation endpoints—without requiring repetitive authentication logic in individual route handlers. ## Configuration and Development Mode Behavior The middleware supports flexible deployment scenarios through environment-based configuration: - **Production/secured mode**: Set `OPEN_NOTEBOOK_PASSWORD` to a strong secret. All clients must include `Authorization: Bearer ` headers. - **Development mode**: If `OPEN_NOTEBOOK_PASSWORD` is unset, the middleware skips authentication checks entirely, allowing unrestricted local development access. ## Client Integration Examples To access protected endpoints, clients must include the Bearer token in the Authorization header: ```python import os import requests BASE = "http://localhost:5055" pwd = os.getenv("OPEN_NOTEBOOK_PASSWORD") # same secret as the server headers = {"Authorization": f"Bearer {pwd}"} resp = requests.get(f"{BASE}/api/notebooks", headers=headers) print(resp.json()) # works only with correct password ``` When authentication fails, the API returns: ```json { "detail": "Invalid password" } ``` The repository includes [`api/client.py`](https://github.com/lfnovo/open-notebook/blob/main/api/client.py), which demonstrates automatic header injection for programmatic access. ## Key Files and Components - **[`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)**: Implements `PasswordAuthMiddleware` with secret loading and Bearer token validation logic. - **[`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py)**: Registers the middleware globally before mounting API routers. - **[`api/client.py`](https://github.com/lfnovo/open-notebook/blob/main/api/client.py)**: Provides example client code that automatically injects the `Authorization` header. - **[`docs/5-CONFIGURATION/security.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/5-CONFIGURATION/security.md)**: Documents the password-based security model for development environments. ## Summary - The `PasswordAuthMiddleware` in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py) implements a shared-secret authentication pattern using Bearer tokens. - All API endpoints are automatically protected because the middleware is added at the application level in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) before any routers. - Authentication requires an `Authorization` header with the format `Bearer `. - Missing or incorrect passwords result in a **401 Unauthorized** response with the JSON detail `"Invalid password"`. - When `OPEN_NOTEBOOK_PASSWORD` is unset, the middleware bypasses checks to facilitate local development. ## Frequently Asked Questions ### What happens if the OPEN_NOTEBOOK_PASSWORD environment variable is not set? If the environment variable is missing, the middleware skips the authentication check entirely. This design allows developers to run the application locally without configuring passwords, while production deployments can enforce security by setting the variable. ### Do I need to add authentication logic to each API route individually? No. Because `PasswordAuthMiddleware` is registered at the FastAPI application level in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py), it intercepts every incoming request before reaching any router. Individual endpoints do not require additional decorators or authentication checks. ### What is the exact format of the Authorization header? The middleware expects an `Authorization` header with the value `Bearer `, where `` matches the `OPEN_NOTEBOOK_PASSWORD` environment variable configured on the server. Requests without this header or with an incorrect token receive a 401 Unauthorized response. ### Where is the authentication middleware initialized in the codebase? The middleware class is defined in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py), and it is instantiated and added to the FastAPI application in [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) via `app.add_middleware(PasswordAuthMiddleware)` before any API routers are mounted.