Skip to content

api-keys.md

Latest commit

 

History

History
178 lines (146 loc) · 8.72 KB

api-keys.md

File metadata and controls

178 lines (146 loc) · 8.72 KB

API Keys & Access Tokens

Complete reference for all credentials used by the Augur stack.

Required (stack won't function without these)

Variable Service Used by Free tier Signup
MONGO_URI_SIGNALS MongoDB Atlas signals-store (database: signals) M0 (512 MB) https://cloud.mongodb.com

Optional API Keys (per domain server)

All domain servers work partially without keys — tools that need a key return a clean error message, other tools in the same server work fine.

Variable Service Used by Free tier Signup
FRED_API_KEY FRED (Federal Reserve) macro_server unlimited https://fred.stlouisfed.org/docs/api/api_key.html
ACLED_EMAIL ACLED (OAuth login) conflict_server research access https://acleddata.com/register/
ACLED_PASSWORD ACLED (OAuth password) conflict_server — same as above
OPENSANCTIONS_API_KEY OpenSanctions (entity + sanctions search) conflict_server free tier https://www.opensanctions.org/api/
UCDP_ACCESS_TOKEN UCDP (armed conflict) conflict_server free (request token) https://ucdp.uu.se/apidocs/
EIA_API_KEY EIA (US energy data) commodities_server unlimited https://www.eia.gov/opendata/register.php
COMTRADE_API_KEY UN Comtrade (trade flows) commodities_server 100 req/day https://comtradeplus.un.org/TradeFlow
GOOGLE_API_KEY Google Civic Info elections_server generous https://console.cloud.google.com/apis/credentials
AISSTREAM_API_KEY AIS Stream (ship tracking) transport_server free tier https://aisstream.io/
OPENSKY_CLIENT_ID OpenSky Network (OAuth2) transport_server free (higher rate limits) https://opensky-network.org/
OPENSKY_CLIENT_SECRET OpenSky Network (OAuth2) transport_server — same as above
CF_API_TOKEN Cloudflare Radar infra_server free https://dash.cloudflare.com/profile/api-tokens
USDA_NASS_API_KEY USDA NASS (ag stats) agri_server unlimited https://quickstats.nass.usda.gov/api/
IDMC_API_KEY IDMC (displacement data) humanitarian_server free (request key) https://www.internal-displacement.org/
RELIEFWEB_APPNAME ReliefWeb (reports/disasters) humanitarian_server free (register appname) https://apidoc.reliefweb.int/

Agents API Key (cron, trigger, bootstrap)

Variable Purpose Where to set
AUGUR_AGENTS_API_KEY Authenticates augur cron, augur trigger, augur bootstrap against LibreChat's Agents API ~/augur/.env
AUGUR_BOOTSTRAP_AGENT_ID Agent ID for augur bootstrap profile seeding ~/augur/.env

How to generate:

  1. Ensure remoteAgents is enabled in librechat.yaml (enabled by default since Augur setup): 
    interface:
  remoteAgents:
    use: true
    create: true
  2. Restart LibreChat: augur restart librechat
  3. In LibreChat UI: Settings > Data controls > Agent API Keys → create a new key
  4. Copy the key to ~/augur/.env: 
    AUGUR_AGENTS_API_KEY=sk-...

These keys are persistent (no expiry), unlike JWT session tokens.

Note: If "Agent API Keys" doesn't appear in Settings, see LibreChat #12149 — a known bug in some v0.8.x versions. As a workaround, use augur token to generate a JWT-based token.

LLM Provider Keys (LibreChat)

Set in ~/LibreChat/.env (not in the signals stack .env). Only one LLM key is needed. See docs/llm-keys.md for the full reference (15+ providers, free tiers, paid tiers, Claude Max subscription).

Variable Service Notes
OPENAI_API_KEY OpenAI Direct API access (paid)
ANTHROPIC_API_KEY Anthropic Direct API access (paid)
OPENROUTER_API_KEY OpenRouter Multi-provider gateway (free + paid)
GROQ_API_KEY Groq Free tier, very fast
GEMINI_API_KEY Google Gemini Free tier, large context
MISTRAL_API_KEY Mistral Free tier, good for code

LibreChat Internal Secrets

Auto-generated by setup.sh on first install. Do not set manually.

Variable Purpose
CREDS_KEY Credential encryption key
CREDS_IV Credential encryption IV
JWT_SECRET JWT token signing
JWT_REFRESH_SECRET JWT refresh token signing

Augur News (Publishing Stack)

Variable Service Used by Free tier Signup
REPLICATE_API_TOKEN Replicate (FLUX.2 image gen) augur_publish pay-per-use (~$0.003/image) https://replicate.com/account/api-tokens
FAL_KEY fal.ai (FLUX.2 fallback) augur_publish pay-per-use https://fal.ai/dashboard/keys
BLUESKY_HANDLE Bluesky (auto-post) augur_publish free https://bsky.app/settings/app-passwords
BLUESKY_APP_PASSWORD Bluesky app password augur_publish — same as above
MASTODON_ACCESS_TOKEN Mastodon (auto-post) augur_publish free Settings > Development > New App
MASTODON_INSTANCE Mastodon instance URL augur_publish — e.g. https://mastodon.social
NTFY_TOPIC ntfy.sh (push notifications) augur_publish + store free https://ntfy.sh

Site configuration (not API keys, but needed for publishing):

Variable Default Purpose
AUGUR_SITE_DIR ~/augur.news Local checkout of GitHub Pages site
AUGUR_SITE_URL https://github.com/ManuelKugelmann/Augur Public URL of the site
AUGUR_SITE_BRANCH augur_news Git branch for publishing

No-Key APIs (28 sources, all free)

These APIs require no authentication and work out of the box:

Server APIs
weather Open-Meteo (forecast + historical + flood), NOAA SWPC (space weather)
disasters USGS Earthquakes, GDACS, NASA EONET
macro World Bank, IMF WEO (FRED needs key)
agri FAOSTAT (USDA NASS needs key)
conflict (ACLED needs OAuth, UCDP needs token, OpenSanctions needs key)
health WHO GHO, WHO Outbreaks, disease.sh, FDA
humanitarian UNHCR, OCHA HDX (IDMC needs key, ReliefWeb needs appname)
elections Wikidata, EU Parliament (Google Civic needs key)
transport OpenSky Network (AIS Stream needs key, OpenSky OAuth2 optional)
water USGS Water Services, US Drought Monitor
infra RIPE Atlas (Cloudflare Radar needs token)

Setup

# 1. Copy template
cp .env.example .env

# 2. Set MongoDB (required)
# Create free M0 cluster at https://cloud.mongodb.com
# Get connection string from: Database > Connect > Drivers
MONGO_URI_SIGNALS=mongodb+srv://user:pass@cluster0.xxxxx.mongodb.net/signals

# 3. Add optional API keys as needed
# Start with FRED (most useful, instant signup)
FRED_API_KEY=your_key_here

Environment variable flow

.env (signals stack)
  │
  ├─ MONGO_URI_SIGNALS ─► signals-store (server.py)
  ├─ PROFILES_DIR ───────► signals-store (server.py)
  └─ API keys ──────────┐
                         │ load_dotenv() in each server
                         │
librechat.yaml           │ env: blocks pass keys explicitly
  ├─ FRED_API_KEY ──────►│ macro_server
  ├─ ACLED_EMAIL ───────►│ conflict_server (OAuth login)
  ├─ ACLED_PASSWORD ────►│ conflict_server (OAuth password)
  ├─ UCDP_ACCESS_TOKEN ─►│ conflict_server
  ├─ OPENSANCTIONS_API_KEY►│ conflict_server
  ├─ EIA_API_KEY ───────►│ commodities_server
  ├─ COMTRADE_API_KEY ──►│ commodities_server
  ├─ GOOGLE_API_KEY ────►│ elections_server
  ├─ AISSTREAM_API_KEY ──► transport_server
  ├─ OPENSKY_CLIENT_ID ──► transport_server (OAuth2)
  ├─ OPENSKY_CLIENT_SECRET► transport_server (OAuth2)
  ├─ CF_API_TOKEN ──────►│ infra_server
  ├─ USDA_NASS_API_KEY ──► agri_server
  ├─ IDMC_API_KEY ──────►│ humanitarian_server
  ├─ RELIEFWEB_APPNAME ──► humanitarian_server
  │
  │ Publishing (augur_publish)
  ├─ REPLICATE_API_TOKEN ► image generation
  ├─ FAL_KEY ─────────────► image generation (fallback)
  ├─ BLUESKY_HANDLE ──────► social auto-post
  ├─ BLUESKY_APP_PASSWORD ► social auto-post
  ├─ MASTODON_ACCESS_TOKEN► social auto-post
  ├─ MASTODON_INSTANCE ───► social auto-post
  ├─ NTFY_TOPIC ──────────► push notifications
  ├─ AUGUR_SITE_DIR ──────► article publishing
  └─ AUGUR_SITE_URL ──────► article URLs