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) |
|
Sign in at fredaccount.stlouisfed.org and request a key (how) |
BLS (Bureau of Labor Statistics) |
|
BLS API registration; optional: without it pyeconomics reads BLS’s keyless API v1 at its lower limits |
BEA (Bureau of Economic Analysis) |
|
BEA API sign-up; BEA calls the key a UserID |
US Census Bureau |
|
Census API key request; required on every query since May 2026 |
OpenFIGI |
|
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:
An argument you pass to a function that fetches data.
The environment variable, such as
FRED_API_KEY.The
.envfile 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.The OS keyring: service
pyeconomics, user name the provider id, when thekeyringextra 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.
The OS keyring (recommended)#
The keyring keeps the key out of files and shell history. Install the extra,
then store each key. pyeconomics keys set asks for the key without showing
it, checks it and stores it (the command line guide has the
details, including --stdin for a key piped from a secrets manager):
pip install "pyeconomics[keyring]"
pyeconomics keys set fred
keyring set pyeconomics fred, the keyring package’s own command, stores the
same entry. pyeconomics keys list shows where each key would be read from,
never its value.
The user name is the provider id: fred, bls, bea, census or
openfigi. macOS uses the Keychain, Windows the Credential Manager, and
Linux the Secret Service (GNOME Keyring or KWallet). If the keyring cannot
be read, pyeconomics skips it with a keyring_backend_failed warning that
names the backend.
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 |
|
macOS |
|
Windows |
|
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.exportand 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:
pyeconomics.tomlin your configuration directory (the.envtable above shows where);pyeconomics.tomlin the working directory;PYECONOMICS_*environment variables.
mode = "library"
offline = false
sec_contact = "Ada Analyst ada.analyst@example.org"
[ttl]
bls = 86400
Setting |
Variable |
Meaning |
|---|---|---|
|
|
|
|
|
Serve only cached data and send no request: |
|
|
Where the cache lives, as an absolute path |
|
|
The name and email address SEC EDGAR requires in each request |
|
|
How long the cache serves a provider’s open data, in seconds; |
|
|
Providers to turn off, a list in |
|
|
Let the MCP server and the AI narrative pass data whose terms are unclear about language models to a model: |
|
|
Turn the optional AI narrative on (The AI narrative); off by default |
|
|
The narrative’s provider: |
|
|
The narrative’s model at that provider; its recorded default when unset |
|
Where |
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
Secretfrom 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 theAuthorization,Cookieand 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:
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.
Update where you keep it. Run
pyeconomics keys set <provider>again, or edit the environment variable or the.envfile. Runpyeconomics keys delete <provider>to remove a stored key.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.
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.