# How to Securely Manage Data Provider API Keys Within OpenBB

> Learn to securely manage OpenBB data provider API keys using environment variables or a local JSON file. Protect sensitive data with Pydantic SecretStr.

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

---

**OpenBB automatically loads API keys from environment variables or a local JSON file, masking them with Pydantic's `SecretStr` to prevent accidental exposure while providing simple programmatic access.**

Managing credentials for multiple financial data providers is a critical security concern when using the OpenBB Platform. The `OpenBB-finance/OpenBB` repository implements a centralized `Credentials` model that securely handles API keys from multiple sources without requiring hard-coded secrets in your analysis scripts. This architecture ensures that sensitive provider tokens remain protected while remaining accessible to the platform's data connectors.

## Understanding OpenBB's Credentials Architecture

The OpenBB Platform uses a dynamic Pydantic model to handle authentication credentials across all data providers. This system prioritizes security by design, ensuring that raw API keys are never accidentally logged or displayed.

### The Credentials Model and SecretStr

At the core of the system is the `Credentials` class defined in [`openbb_platform/core/openbb_core/app/model/credentials.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/credentials.py). This model dynamically generates fields based on registered data providers, typing each API key as `SecretStr`【source: `Credentials` model implementation】. 

`SecretStr` is a Pydantic type that masks the underlying value during string conversion or JSON serialization. When you print a `Credentials` object, you see `**********` instead of the actual key, preventing accidental exposure in notebooks or logs.

### Three Secure Sources for API Keys

The `CredentialsLoader.load` method (lines 26-48) aggregates credentials from three distinct sources in order of precedence:

1. **User settings file** (`~/.openbb_platform/user_settings.json`) – A local JSON file storing persistent credentials【source: lines 26-33】
2. **Environment variables** – Any variable ending with `API_KEY` (e.g., `ALPHAVANTAGE_API_KEY`)【source: lines 41-48】
3. **Provider registry** – Each provider declares required credential names via `ProviderInterface.credentials` (lines 25-28), which the loader uses to validate and map incoming values

Environment variables take precedence over the user settings file, allowing temporary overrides without modifying persistent storage.

## Where OpenBB Stores API Keys

Understanding the physical storage locations helps implement proper security hygiene and `.gitignore` rules.

### Environment Variables

OpenBB scans `os.environ` for any key ending with the suffix `API_KEY`. This convention allows the platform to automatically recognize provider credentials without explicit configuration. For example, setting `export FRED_API_KEY="your_key"` makes the Federal Reserve Economic Data provider immediately available.

### User Settings File Location

The platform stores persistent credentials in `~/.openbb_platform/user_settings.json`, defined in [`openbb_platform/core/openbb_core/app/constants.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/constants.py) (line 7) as `USER_SETTINGS_PATH`. This file is automatically created when you use the `openbb config set` CLI command or programmatically update settings.

The default location ensures the file resides outside version control directories, reducing the risk of accidental commits.

## How to Configure API Keys in OpenBB

You can configure credentials through three methods, depending on your security requirements and deployment environment.

### Method 1: Environment Variables (Preferred)

For production deployments and CI/CD pipelines, environment variables provide the most secure approach. They exist only in memory and never persist to disk in plain text within the project directory.

```bash

# Linux/macOS

export ALPHAVANTAGE_API_KEY="your_key_here"
export FRED_API_KEY="your_fred_key"

# Windows PowerShell

$env:ALPHAVANTAGE_API_KEY="your_key_here"

```

After setting these, OpenBB automatically detects them on the next initialization. No additional code is required to load these values.

### Method 2: User Settings File

For local development where you want credentials to persist across sessions, use the user settings file. You can modify this file directly or use the CLI:

```bash

# Using OpenBB CLI

openbb config set credentials.alpha_vantage_api_key "your_key_here"

```

This command writes to `~/.openbb_platform/user_settings.json`:

```json
{
  "credentials": {
    "alpha_vantage_api_key": "your_key_here"
  }
}

```

### Method 3: Programmatic Configuration

For advanced use cases, you can directly manipulate the settings file using Python:

```python
import json
from pathlib import Path
from openbb_core.app.constants import USER_SETTINGS_PATH

# Load existing settings or create new structure

settings_path = Path(USER_SETTINGS_PATH)
settings = {}
if settings_path.exists():
    settings = json.loads(settings_path.read_text())

# Update credentials section

settings.setdefault("credentials", {})["alpha_vantage_api_key"] = "my-new-key"
settings_path.write_text(json.dumps(settings, indent=2))
print(f"Updated {USER_SETTINGS_PATH}")

```

## Accessing and Using Credentials in Code

Once configured, accessing credentials in your OpenBB scripts is straightforward. The `Credentials` model handles all loading logic automatically.

### Loading Credentials

```python
from openbb_core.app.model.credentials import Credentials

# Automatically loads from env vars and user_settings.json

creds = Credentials()

# Access returns a SecretStr object, not the raw string

print(creds.alpha_vantage_api_key)  # Output: **********

```

### Retrieving Raw Values

When you need the actual key value (for example, to pass to a third-party library), use the `get_secret_value()` method:

```python

# Safely extract the raw string when needed

plain_key = creds.alpha_vantage_api_key.get_secret_value()
print("Key length:", len(plain_key))

```

### Displaying All Credentials

To audit which providers are configured without exposing values in logs, use the `show()` method:

```python

# Display all configured credentials (masked by default)

Credentials().show()

```

According to the source code in [`credentials.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/credentials.py) (lines 11-19), the `show()` method deliberately unmasks values only when explicitly requested and outputs a JSON-serialized view rather than raw secret objects.

## Security Best Practices for OpenBB API Keys

Implementing proper security hygiene prevents credential leakage in version control or logs.

### Conflict Resolution and Precedence

The `CredentialsLoader` implements a clear precedence order (lines 41-48 in [`credentials.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/credentials.py)):

1. **Environment variables** override user settings
2. **User settings** provide fallback values

This hierarchy allows you to set permanent keys in [`user_settings.json`](https://github.com/OpenBB-finance/OpenBB/blob/main/user_settings.json) while temporarily overriding them via environment variables for specific runs or CI/CD pipelines.

### Never Commit Secrets

The OpenBB platform automatically stores [`user_settings.json`](https://github.com/OpenBB-finance/OpenBB/blob/main/user_settings.json) outside your project directory in `~/.openbb_platform/`, as defined in [`constants.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/constants.py) (line 7). This location is naturally excluded from Git repositories.

However, if you manually move or copy this file, ensure you:
- Add `*.json` with credential patterns to `.gitignore`
- Never hard-code keys in Jupyter notebooks or Python scripts that might be shared
- Use environment variables for any repository-contained configuration examples

## Summary

- OpenBB's `Credentials` model in [`openbb_platform/core/openbb_core/app/model/credentials.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/credentials.py) automatically loads API keys from environment variables and `~/.openbb_platform/user_settings.json`.
- Environment variables ending with `API_KEY` take precedence over stored settings, enabling secure temporary overrides.
- All credentials are typed as Pydantic `SecretStr` to prevent accidental exposure in logs or print statements.
- The `Credentials.show()` method provides controlled access to credential status without exposing raw values by default.
- Store sensitive keys in environment variables for production use, and rely on the user settings file only for local development persistence.

## Frequently Asked Questions

### Where does OpenBB store API keys locally?

OpenBB stores persistent API keys in `~/.openbb_platform/user_settings.json`, as defined in [`openbb_platform/core/openbb_core/app/constants.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/constants.py) (line 7). This location resides in the user's home directory, outside of project repositories, to prevent accidental commits to version control. The file is created automatically when you use the `openbb config set` command or programmatically update credentials.

### How do I override a stored API key temporarily?

Set an environment variable with the same name as the credential, ensuring it ends with `API_KEY` (e.g., `export ALPHAVANTAGE_API_KEY="new_key"`). According to the `CredentialsLoader.load` implementation in [`credentials.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/credentials.py) (lines 41-48), environment variables automatically override values stored in [`user_settings.json`](https://github.com/OpenBB-finance/OpenBB/blob/main/user_settings.json). This approach is ideal for CI/CD pipelines or testing different keys without modifying your persistent configuration.

### Is it safe to store API keys in user_settings.json?

Yes, provided you follow security best practices. The default location (`~/.openbb_platform/user_settings.json`) is outside typical Git repositories, reducing the risk of accidental commits. However, the file stores keys in plain text, so you should set appropriate file permissions (readable only by your user) and avoid copying this file to shared drives or cloud storage. For maximum security, prefer environment variables which exist only in memory.

### How does OpenBB prevent accidental exposure of API keys?

OpenBB uses Pydantic's `SecretStr` type for all credential fields in the `Credentials` model, ensuring that values are masked as `**********` when printed, logged, or converted to strings. The `Credentials.show()` method (lines 11-19 in [`credentials.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/credentials.py)) provides controlled unmasking only when explicitly requested, outputting a JSON-serialized view rather than raw secret objects. This design prevents credentials from appearing in Jupyter notebook outputs, logs, or error tracebacks by default.