How to Add Authentication to OpenBB REST API Using Environment Variables

You can secure the OpenBB REST API with HTTP Basic authentication by setting OPENBB_API_AUTH=true, OPENBB_API_USERNAME, and OPENBB_API_PASSWORD in your environment variables, which activates a FastAPI security dependency that validates credentials using constant-time comparison.

The OpenBB Platform provides a configurable REST API that supports HTTP Basic authentication controlled entirely through environment variables. This approach allows you to secure your financial data endpoints without modifying source code or configuration files. In the OpenBB-finance/OpenBB repository, the authentication system is implemented via the Env singleton and FastAPI dependency injection, making it straightforward to add authentication to the OpenBB REST API using environment variables.

How Environment Variable Authentication Works in OpenBB

The authentication flow relies on three core components working together. First, the Env class in openbb_platform/core/openbb_core/env.py reads environment variables and exposes properties like API_AUTH, API_USERNAME, and API_PASSWORD. When OPENBB_API_AUTH is set to true, the FastAPI application in openbb_platform/core/openbb_core/api/rest_api.py injects an HTTPBasic security dependency into protected endpoints.

The actual credential validation happens in openbb_platform/core/openbb_core/api/auth/user.py, where the authenticate_user function compares supplied credentials against your environment variables using secrets.compare_digest. This constant-time comparison prevents timing attacks. If credentials are missing or invalid, the API returns a 401 Unauthorized response with the detail message "Incorrect email or password".

Configuring Authentication via Environment Variables

Enable Authentication

Set OPENBB_API_AUTH=true in your .env file or export it directly in your shell. This boolean flag tells the OpenBB Platform to require credentials on every protected endpoint.

Define Credentials

Specify your username and password using OPENBB_API_USERNAME and OPENBB_API_PASSWORD. These values are read at startup and cached in the Env singleton for the duration of the session.

# .env (placed at <OPENBB_DIRECTORY>/.env)

OPENBB_API_AUTH=true
OPENBB_API_USERNAME=my_user
OPENBB_API_PASSWORD=super_secret

Optional Extension Variable

An additional variable, OPENBB_API_AUTH_EXTENSION, is available for custom extensions that require additional authentication metadata, though it is not required for basic HTTP authentication.

Starting the API and Verifying Authentication

When you launch the server using Uvicorn, the startup banner printed by rest_api.py indicates the current authentication mode:

uvicorn openbb_core.api.rest_api:app --reload

Look for the console output:

Authentication: ENABLED

If the variables are missing or set to false, the banner displays:

Authentication: DISABLED

Making Authenticated API Requests

Once enabled, every request must include valid HTTP Basic authentication headers. You can test this using curl with the -u flag:

curl -u my_user:super_secret http://localhost:8000/api/v1/commands/...

If you omit credentials or provide invalid ones, the API returns:

{
  "detail": "Incorrect email or password"
}

The authenticate_user dependency automatically validates the username and password against your environment variables before allowing access to the underlying endpoint logic.

Disabling Authentication

To run the API without authentication, either remove the OPENBB_API_AUTH variable or set it to false:

OPENBB_API_AUTH=false

Upon restart, the startup banner will show "Authentication: DISABLED", and the HTTPBasic dependency will no longer be injected into the router, allowing unrestricted access to all endpoints.

Summary

• Environment-based control: Authentication is toggled entirely through OPENBB_API_AUTH, OPENBB_API_USERNAME, and OPENBB_API_PASSWORD without code changes.
• Secure validation: Credentials are verified using secrets.compare_digest in openbb_platform/core/openbb_core/api/auth/user.py to prevent timing attacks.
• FastAPI integration: The system uses HTTPBasic security dependencies injected conditionally based on the Env.API_AUTH flag.
• Startup verification: The banner in rest_api.py confirms whether authentication is enabled or disabled when the server starts.
• Optional extensions: OPENBB_API_AUTH_EXTENSION provides hooks for custom authentication extensions beyond basic auth.

Frequently Asked Questions

What environment variables are required to enable authentication in OpenBB?

You need three variables: OPENBB_API_AUTH set to true to enable the feature, plus OPENBB_API_USERNAME and OPENBB_API_PASSWORD to define the valid credentials. These are read by the Env class in openbb_platform/core/openbb_core/env.py at startup.

How does OpenBB prevent timing attacks when validating passwords?

The authenticate_user function in openbb_platform/core/openbb_core/api/auth/user.py uses Python's secrets.compare_digest to compare the provided credentials against environment variables. This method performs a constant-time comparison that prevents attackers from deducing valid credentials based on response timing.

Can I use external authentication providers like OAuth or API keys?

The current implementation in the OpenBB repository supports HTTP Basic authentication via environment variables. While OPENBB_API_AUTH_EXTENSION exists for custom extension hooks, the core platform does not natively implement OAuth or API key authentication in the files analyzed. You would need to implement custom middleware or extend the authentication dependency in auth/user.py.

Why does my API still show "Authentication: DISABLED" after setting the variables?

Ensure your .env file is located at the correct path (<OPENBB_DIRECTORY>/.env) and that you have restarted the Uvicorn server after making changes. The Env singleton reads these values once at startup, so runtime changes require a restart to take effect.

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