# How to Debug OpenBB REST API Authentication Issues: A Step-by-Step Guide

> Effectively debug OpenBB REST API authentication issues. Learn to check startup banners, verify environment variables, and inspect auth service loading for quick resolution.

- Repository: [OpenBB/OpenBB](https://github.com/OpenBB-finance/OpenBB)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To debug OpenBB REST API authentication issues, check the startup banner for "Authentication: ENABLED", verify the `API_AUTH` and `API_AUTH_EXTENSION` environment variables, and inspect the `AuthService` loading flow in [`openbb_platform/core/openbb_core/app/service/auth_service.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/service/auth_service.py).**

OpenBB exposes its financial data functionality through a FastAPI-based REST layer where authentication is optional and provided by a pluggable auth extension. When you encounter 401 or 403 errors while accessing protected endpoints, a systematic debugging approach based on the platform's source code will help you pinpoint whether the issue stems from configuration, missing extensions, or custom validation logic.

## Understanding the OpenBB REST API Authentication Architecture

### The Auth Extension System

OpenBB uses an extension-based architecture for authentication. The core platform in [`openbb_platform/core/openbb_core/api/rest_api.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py) initializes the FastAPI application and delegates authentication to an external extension specified via environment variables. When the `API_AUTH` flag is enabled, the platform attempts to load the extension named in `API_AUTH_EXTENSION` through the `AuthService` class.

### Key Components and File Locations

The authentication flow involves several critical files:

- **[`openbb_platform/core/openbb_core/api/rest_api.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py)** (lines 24-30): Prints the startup banner showing whether authentication is enabled and adds the auth router to the FastAPI app.
- **[`openbb_platform/core/openbb_core/app/service/auth_service.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/service/auth_service.py)**: Contains the `AuthService` class with `_is_installed` and `_load_extension` methods that handle extension discovery and loading.
- **[`openbb_platform/core/openbb_core/env.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/env.py)**: Reads environment variables including `API_AUTH`, `API_AUTH_EXTENSION`, and `DEV_MODE`.
- **[`openbb_core/api/router/user.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_core/api/router/user.py)**: Defines the `default_auth_hook` used when no extension is loaded, which performs no validation.

## Step-by-Step Debugging Workflow

### Step 1: Check the Platform Startup Banner

When the OpenBB server starts, examine the console output for the authentication status banner. Look for the line indicating `Authentication: ENABLED` or `Authentication: DISABLED`.

If the banner shows **DISABLED** despite expecting authentication, the auth extension isn't loading. This check corresponds to the startup logic in [`openbb_platform/core/openbb_core/api/rest_api.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py) where the banner prints the status derived from environment configuration.

### Step 2: Verify Environment Variables

Confirm three critical environment variables are set correctly:

- **`API_AUTH`**: Must be set to a truthy value (e.g., `1`, `true`) to enable the authentication banner flag.
- **`API_AUTH_EXTENSION`**: Must contain the exact package name of the installed auth extension (e.g., `openbb-auth-jwt`).
- **`DEV_MODE`**: When set to `1`, forces the platform to always add the auth router even if the extension isn't properly detected.

These variables are processed in [`openbb_platform/core/openbb_core/env.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/env.py). Export them before launching the server:

```bash
export API_AUTH=1
export API_AUTH_EXTENSION=openbb-auth-jwt
export DEV_MODE=0

```

### Step 3: Confirm the Auth Extension Installation

The `AuthService` class in [`openbb_platform/core/openbb_core/app/service/auth_service.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/service/auth_service.py) uses the `_is_installed` method to verify the extension package exists on the Python path. If the extension specified in `API_AUTH_EXTENSION` isn't installed, the service falls back to the default router with no authentication.

Verify installation using pip:

```bash
pip list | grep openbb-auth

```

If the extension is missing, install it:

```bash
pip install openbb-auth-jwt

```

Check the logs for the message `Loaded auth_extension: <name>` which is logged by `AuthService` when successfully loaded.

### Step 4: Inspect the Loaded Router

When the auth extension loads successfully, its router is added to the FastAPI application through `AppLoader.add_routers` in [`openbb_platform/core/openbb_core/api/rest_api.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py). If the router is missing, endpoints won't enforce authentication.

Examine the startup logs to confirm the router was added. If running in `DEV_MODE`, the platform explicitly adds the auth router regardless of extension status, which helps isolate whether the issue is routing or validation.

### Step 5: Test with Swagger UI and Curl

Navigate to `http://<host>:<port>/docs` to access the interactive Swagger UI. Protected endpoints display a lock icon and list the required `Authorization` header.

Test authentication using curl:

```bash
curl -H "Authorization: Bearer <your-token>" http://localhost:8000/api/v1/protected-endpoint

```

If you receive a 401 response despite providing a valid token, the issue lies in the custom auth extension's `auth_hook` implementation. The hook typically extracts the bearer token, validates it (e.g., JWT verification or API key lookup), and raises `HTTPException(status_code=401)` on failure.

## Common Authentication Pitfalls and Solutions

**Banner shows DISABLED but auth is expected**
- **Cause**: The `API_AUTH` environment variable is false or missing.
- **Fix**: Export `API_AUTH=1` before launching the server.

**401 on every request with a valid token**
- **Cause**: The auth extension isn't loaded due to a mismatch in `API_AUTH_EXTENSION` name.
- **Fix**: Verify the extension name matches the installed package (e.g., `openbb-auth-jwt`).

**No Authorization header in Swagger UI**
- **Cause**: Using the default router without an auth extension installed.
- **Fix**: Install and configure an auth extension, then restart the platform.

**Logs contain "Extension 'xyz' is not installed"**
- **Cause**: The extension package isn't on the Python path.
- **Fix**: Run `pip install openbb-auth-xyz` or add it to your [`pyproject.toml`](https://github.com/OpenBB-finance/OpenBB/blob/main/pyproject.toml).

**Custom auth hook raises unexpected exceptions**
- **Cause**: Bug in the extension's validation logic.
- **Fix**: Inspect the extension's `auth_hook` implementation and add logging to catch validation errors.

## Summary

- **Check the startup banner** in [`openbb_platform/core/openbb_core/api/rest_api.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py) to confirm whether authentication is enabled or disabled.
- **Verify environment variables** (`API_AUTH`, `API_AUTH_EXTENSION`, `DEV_MODE`) in [`openbb_platform/core/openbb_core/env.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/env.py) to ensure proper configuration.
- **Confirm extension installation** using `AuthService._is_installed` in [`openbb_platform/core/openbb_core/app/service/auth_service.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/service/auth_service.py) to verify the auth package is discoverable.
- **Inspect router loading** through `AppLoader.add_routers` to ensure the auth router is attached to the FastAPI application.
- **Test endpoints** using Swagger UI and curl to isolate whether issues stem from routing or the custom `auth_hook` validation logic.

## Frequently Asked Questions

### Why does my OpenBB server show "Authentication: DISABLED" on startup?

The startup banner in [`openbb_platform/core/openbb_core/api/rest_api.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/api/rest_api.py) prints this status when the `API_AUTH` environment variable is not set to a truthy value. To enable authentication, export `API_AUTH=1` before starting the server and ensure you have specified a valid `API_AUTH_EXTENSION` name.

### How do I know if my auth extension is actually loading?

Check the server logs for the message `Loaded auth_extension: <name>` which is emitted by `AuthService` in [`openbb_platform/core/openbb_core/app/service/auth_service.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/service/auth_service.py). If you see `Extension 'xyz' is not installed` instead, the package is missing from your Python environment or the name in `API_AUTH_EXTENSION` doesn't match the installed package name.

### What is the difference between the default auth hook and a custom extension?

The `default_auth_hook` defined in [`openbb_core/api/router/user.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_core/api/router/user.py) is a no-op function that performs no validation and never rejects requests. When you install a custom auth extension, it replaces this hook with its own implementation that typically validates bearer tokens or API keys and raises `HTTPException(status_code=401)` for invalid credentials. If you're receiving 401 errors, you are hitting a custom hook, not the default.