Keys and configuration#

A few data sources ask for a free API key. pyeconomics reads a key only through its key chain, holds it in memory as a Secret, and never logs, prints, caches or exports it. This page covers where to get each key, where to put it, the settings file, what stays private, and what to do if a key leaks. New to keys? Data and keys walks through setting one.

Where to register#

Source

Environment variable

Where to get a key

FRED and ALFRED (St. Louis Fed)

FRED_API_KEY

Sign in at fredaccount.stlouisfed.org and request a key (how)

BLS (Bureau of Labor Statistics)

BLS_API_KEY

BLS API registration; optional: without it pyeconomics reads BLS’s keyless API v1 at its lower limits

BEA (Bureau of Economic Analysis)

BEA_API_KEY

BEA API sign-up; BEA calls the key a UserID

US Census Bureau

CENSUS_API_KEY

Census API key request; required on every query since May 2026

OpenFIGI

OPENFIGI_API_KEY

Optional, for higher rate limits: sign up as the OpenFIGI documentation describes

Every variable is the provider’s id in capitals followed by _API_KEY:

>>> from pyeconomics.data import key_variable
>>> key_variable("fred")
'FRED_API_KEY'

How pyeconomics finds a key#

For each provider, pyeconomics takes the first key it finds, in this order:

  1. An argument you pass to a function that fetches data.

  2. The environment variable, such as FRED_API_KEY.

  3. The .env file in your pyeconomics configuration directory. A variable set in the real environment always wins over the file, and the file is never loaded into the environment.

  4. The OS keyring: service pyeconomics, user name the provider id, when the keyring extra is installed.

An empty value counts as unset. If no source has a key, the error names the provider, its variable, the keyring command and this page, never a value.

To check for a key without reading it, use has_key. It returns only True or False:

>>> from pyeconomics.data import has_key
>>> has_key("fred")  # True once a key is set
False

Setting a key#

Replace <key> below with the key the source issued you.

An environment variable#

On macOS and Linux:

export FRED_API_KEY='<key>'

In Windows PowerShell:

$env:FRED_API_KEY = '<key>'

The .env file#

Put one NAME=VALUE per line in the .env file in your configuration directory:

# pyeconomics keys
FRED_API_KEY=<key>
BLS_API_KEY='<key>'

System

File

Linux

~/.config/pyeconomics/.env (or $XDG_CONFIG_HOME/pyeconomics/.env)

macOS

~/Library/Application Support/pyeconomics/.env

Windows

%LOCALAPPDATA%\pyeconomics\.env

PYECONOMICS_CONFIG_DIR moves the directory. pyeconomics never reads a .env file anywhere else, including your project or working directory.

The parser is strict, and nothing in the file is ever executed or expanded:

  • A value is taken literally. $HOME, ${HOME} and backslashes stay as written.

  • Quote a value with single or double quotes on one line. A bare value has no spaces, quotes or #.

  • Lines starting with # are comments, as is a # after a space at the end of a line.

  • export and multi-line values are errors, as is a name set twice. An error names the line number, never the line.

On macOS and Linux, make the file readable by you alone:

chmod 600 ~/.config/pyeconomics/.env

Otherwise pyeconomics warns with credentials_file_permissions.

Settings: pyeconomics.toml#

Settings come from three layers. Each one overrides the one before it, key by key:

  1. pyeconomics.toml in your configuration directory (the .env table above shows where);

  2. pyeconomics.toml in the working directory;

  3. PYECONOMICS_* environment variables.

mode = "library"
offline = false
sec_contact = "Ada Analyst ada.analyst@example.org"

[ttl]
bls = 86400

Setting

Variable

Meaning

mode

PYECONOMICS_MODE

library (the default), or hosted, which serves only sources whose licence allows a hosted service

offline

PYECONOMICS_OFFLINE

Serve only cached data and send no request: 1, true, yes or on

cache_dir

PYECONOMICS_CACHE_DIR

Where the cache lives, as an absolute path

sec_contact

PYECONOMICS_SEC_CONTACT

The name and email address SEC EDGAR requires in each request

[ttl] provider

PYECONOMICS_TTL_<PROVIDER>

How long the cache serves a provider’s open data, in seconds; 0 turns that provider’s cache off (the cache)

disabled_providers

PYECONOMICS_DISABLED_PROVIDERS

Providers to turn off, a list in pyeconomics.toml or ids separated by commas or spaces in the variable (see below)

allow_unclear_llm_use

PYECONOMICS_ALLOW_UNCLEAR_LLM_USE

Let the MCP server and the AI narrative pass data whose terms are unclear about language models to a model: 1, true, yes or on (The MCP server, The AI narrative); data whose terms forbid it never is

ai_enabled

PYECONOMICS_AI_ENABLED

Turn the optional AI narrative on (The AI narrative); off by default

ai_provider

PYECONOMICS_AI_PROVIDER

The narrative’s provider: openai (the default), anthropic, gemini or openrouter

ai_model

PYECONOMICS_AI_MODEL

The narrative’s model at that provider; its recorded default when unset

PYECONOMICS_CONFIG_DIR

Where pyeconomics.toml and .env are read from

The cache directory defaults to ~/.cache/pyeconomics on Linux, ~/Library/Caches/pyeconomics on macOS and %LOCALAPPDATA%\pyeconomics\Cache on Windows. The files and variables are read once per process. configure overrides settings from Python for the rest of the process, in every thread, so a server configures once at start and never per request:

>>> from pyeconomics.data import configure, settings
>>> configure(offline=True).offline
True
>>> settings().mode
'library'

pyeconomics.toml holds settings only. Any key whose name suggests a credential (key, token, secret, password, credential or auth) is refused with a ConfigError that names the key, never its value. Keys go in the keyring, an environment variable or the .env file. The one PYECONOMICS_* variable named like a credential is the hosted server’s own, PYECONOMICS_EDGE_CREDENTIAL (The REST API), which these settings ignore.

Turning a source off#

When a source fails or starts answering wrong values, disabled_providers turns it off without a new release: the provider is refused before any cache read or request (SourceDisabledError, the source-disabled problem), a concept passes over it to its next candidate (the skip is recorded as skipped_<provider>_disabled in the data source’s warnings), and pyeconomics data sources marks it in a Disabled column.

PYECONOMICS_DISABLED_PROVIDERS="bls, fred" pyeconomics data get us.unemployment.rate
>>> from pyeconomics.data import configure
>>> configure(disabled_providers=["bls"]).disabled_providers
('bls',)
>>> configure(disabled_providers=()).disabled_providers
()

What is never logged or stored#

  • A key is a Secret from the moment it is read. It prints as <Secret fred: redacted>, and pickling and JSON refuse it.

  • Once read, a key is scrubbed from every log record of every logger, URL encoded or not. That includes the request lines urllib3 writes at DEBUG, which carry FRED’s key in the query string. It is also scrubbed from pyeconomics’ own warnings and error messages.

  • The query parameters that carry keys (api_key, registrationkey, UserID, key, token) are removed from any URL before a message or a log line holds it, and the Authorization, Cookie and key headers are dropped.

  • Errors name a provider, a variable, a setting or a line number. They never name a value or a file path, and a failed request is reported without the original exception attached.

  • Manifests, results and their exports (JSON, pandas, Parquet) carry no key, no SEC contact, no path and no environment value.

  • The SEC contact is sent only in EDGAR’s User-Agent header. It prints as asterisks and is scrubbed like a key everywhere else.

  • FRED and ALFRED data are never written to disk, as FRED’s terms require, and neither is any source or series whose terms forbid storage. What the cache does store is canonical JSON of data, never a key, and the file is readable by your user only (the cache).

If a key leaks#

Treat a key that reached a log, a notebook, a commit, a chat or a shared file as public:

  1. Replace it at the source. Request a new key, and delete the old one where the source allows it: FRED’s API keys page, or a new registration with BLS, BEA, the Census Bureau or OpenFIGI.

  2. Update where you keep it. Run pyeconomics keys set <provider> again, or edit the environment variable or the .env file. Run pyeconomics keys delete <provider> to remove a stored key.

  3. Remove the copies. Check shell history, notebook outputs, CI logs and commit history. A key pushed to a repository stays in its history until the history is rewritten, so replacing the key is what matters.

  4. If pyeconomics leaked it, through a log line, an error or an export, report it privately through the security policy. The maintainers ship a patched release and publish an advisory.