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

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.

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 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 (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: Contains the AuthService class with _is_installed and _load_extension methods that handle extension discovery and loading.
• 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: 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 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. Export them before launching the server:

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 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:

pip list | grep openbb-auth

If the extension is missing, install it:

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. 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:

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.

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 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 to ensure proper configuration.
• Confirm extension installation using AuthService._is_installed in 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}