# Password-Based Authentication for Open Notebook API Endpoints: Implementation Guide

> Implement password-based authentication for Open Notebook API endpoints. Secure your HTTP API with Bearer tokens and global middleware. Learn more.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-07-02

---

**Open Notebook protects its HTTP API using a lightweight Bearer token scheme that reads credentials from environment variables or Docker secrets, enforced globally via `PasswordAuthMiddleware` in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py).**

The [lfnovo/open-notebook](https://github.com/lfnovo/open-notebook) repository implements a deliberately simple password-based authentication layer designed for development flexibility while supporting secure production deployments. This mechanism guards all API endpoints through a single environment variable and standard HTTP Authorization headers.

## How Password-Based Authentication Works

The authentication system centers on three core components: a secret loading utility, a FastAPI middleware, and an optional route-level dependency.

### Password Source and Configuration

The system retrieves credentials using the `get_secret_from_env` function defined in **[`open_notebook/utils/encryption.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/encryption.py)** (lines 29-38). This helper first checks for a `*_FILE` variant of the environment variable—specifically `OPEN_NOTEBOOK_PASSWORD_FILE`—enabling Docker secret patterns. If the file path exists, the password is read from disk; otherwise, it falls back to the raw `OPEN_NOTEBOOK_PASSWORD` value.

```bash

# Docker secret pattern

export OPEN_NOTEBOOK_PASSWORD_FILE=/run/secrets/open_notebook_password

# Standard environment variable

export OPEN_NOTEBOOK_PASSWORD=my-secure-password

```

### Global Middleware Protection

Every incoming request passes through `PasswordAuthMiddleware`, implemented in **[`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)** (lines 19-71). During initialization, the middleware stores the password retrieved by `get_secret_from_env`. If no password is configured, the middleware short-circuits and allows all requests to proceed, leaving the API open by default.

The middleware explicitly excludes specific routes from authentication checks:
- Root path (`/`)
- Health checks (`/health`)
- Documentation endpoints (`/docs`, `/redoc`, [`/openapi.json`](https://github.com/lfnovo/open-notebook/blob/main//openapi.json))
- CORS pre-flight `OPTIONS` requests

These exclusions are hardcoded in **[`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)** (lines 35-38).

### Request Validation Flow

For protected endpoints, the middleware inspects the `Authorization` header for the format `Bearer <password>`. Missing, malformed, or incorrect tokens trigger a `401 Unauthorized` response with a `WWW-Authenticate: Bearer` header, as implemented in **[`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)** (lines 44-71).

Example error responses include:

```json
{"detail": "Missing authorization header"}

```

```json
{"detail": "Invalid password"}

```

### Optional Per-Route Validation

Individual routes can bypass the global middleware and instead depend on the `check_api_password` helper function (lines 82-94 in **[`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py)**). This function performs identical verification logic but allows granular control, applying authentication only where explicitly injected.

### Authentication Status Endpoint

The router in **[`api/routers/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/routers/auth.py)** exposes a public `GET /auth/status` endpoint (lines 13-27) that reports whether authentication is enabled. This allows clients to probe the server's configuration before attempting protected operations.

## Configuration Reference

| Variable | Description | Example |
|----------|-------------|---------|
| `OPEN_NOTEBOOK_PASSWORD` | Plain-text password for API access | `super-secret-pwd` |
| `OPEN_NOTEBOOK_PASSWORD_FILE` | Path to Docker secret file | `/run/secrets/open_notebook_password` |

If **neither** variable is set, the API runs without authentication—suitable for local development but requiring immediate attention before production deployment.

## Security Considerations

The password-based authentication implementation follows specific security patterns:

- **Memory-only storage**: The password is read once at startup and stored in memory; it is never logged to disk or persisted in application state.
- **No rate limiting**: The mechanism does not implement account lockout or brute-force protection. Production deployments must add these controls at a reverse-proxy or API gateway layer.
- **TLS requirement**: Because credentials use the Bearer scheme transmitted in HTTP headers, all production traffic must terminate TLS before reaching the Open Notebook API. The default development server runs on unencrypted HTTP.

## Implementation Examples

### Enabling Authentication with Docker Secrets

Create a secret file and reference it via environment variable:

```bash
echo "my-strong-pwd" > /run/secrets/open_notebook_password
export OPEN_NOTEBOOK_PASSWORD_FILE=/run/secrets/open_notebook_password

# Start via Docker Compose

docker compose up api

```

### Enabling Authentication via Environment Variable

```bash
export OPEN_NOTEBOOK_PASSWORD=my-strong-pwd
uvicorn api.main:app --host 0.0.0.0 --port 5055

```

### Calling Protected Endpoints with curl

```bash
curl -H "Authorization: Bearer my-strong-pwd" \
     http://localhost:5055/notebooks

```

### Checking Authentication Status Programmatically

```python
import httpx

resp = httpx.get("http://localhost:5055/auth/status")
print(resp.json())

# => {"auth_enabled": true, "message": "Authentication is required"}

```

## Summary

- Open Notebook uses `OPEN_NOTEBOOK_PASSWORD` or `OPEN_NOTEBOOK_PASSWORD_FILE` environment variables to configure API protection.
- The `PasswordAuthMiddleware` in [`api/auth.py`](https://github.com/lfnovo/open-notebook/blob/main/api/auth.py) enforces Bearer token validation on all routes except documentation, health checks, and CORS pre-flight requests.
- Authentication is disabled by default when no password is configured, making the system open for local development.
- The `/auth/status` endpoint provides a programmatic way to detect if authentication is active.
- Production deployments require TLS termination and external rate limiting, as the built-in system lacks brute-force protection.

## Frequently Asked Questions

### How do I enable password-based authentication in Open Notebook?

Set the `OPEN_NOTEBOOK_PASSWORD` environment variable to a non-empty string before starting the API server. Alternatively, use `OPEN_NOTEBOOK_PASSWORD_FILE` to point to a Docker secret file. The middleware automatically detects these variables at startup via the `get_secret_from_env` function in [`open_notebook/utils/encryption.py`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/utils/encryption.py).

### Which API routes are excluded from authentication?

The `PasswordAuthMiddleware` explicitly bypasses authentication for the root path (`/`), health endpoint (`/health`), documentation interfaces (`/docs`, `/redoc`), the OpenAPI specification ([`/openapi.json`](https://github.com/lfnovo/open-notebook/blob/main//openapi.json)), and all `OPTIONS` requests. These exclusions allow health checks and CORS pre-flight requests to succeed without credentials.

### Can I use Docker secrets instead of environment variables?

Yes. The `get_secret_from_env` utility supports the Docker secret pattern. Set `OPEN_NOTEBOOK_PASSWORD_FILE` to the path of your secret file (e.g., `/run/secrets/open_notebook_password`). The system reads the file content and uses it as the authentication password, falling back to the raw `OPEN_NOTEBOOK_PASSWORD` variable only if the file path is unspecified or inaccessible.

### Does Open Notebook implement rate limiting for failed authentication attempts?

No. The authentication layer does not include rate limiting, account lockout, or IP-based throttling. For production deployments, implement these protections at a reverse proxy (such as Nginx or Traefik) or API gateway layer to prevent brute-force attacks against the password-based authentication endpoints.