API Keys

This page is the single source on which provider keys PolitiClaw uses, what each unlocks, and how to set them. The config schema declares only the wired keys listed below; for the per-provider runtime status (with source paths and tier), the authoritative source is Generated Source Coverage.

Which key unlocks what

Three keys cover the wired runtime today.

Key	Required?	What it unlocks
apiDataGov	required for federal bills, votes, finance	Federal bill search and detail, House roll-call vote ingest, committee schedule, FEC OpenFEC candidate finance
googleCivic	required for ballot tools	Ballot snapshots, contest framing, polling-place lookup, election dates
geocodio	optional	Faster reps-by-address resolution. Without it, the zero-key local shapefile path is used.

Senate roll-call votes ingest through voteview.com (zero-key), and the local shapefile path covers reps-by-address without geocodio. Neither needs configuration beyond running politiclaw_configure once.

For planned providers that are not yet wired (state bills, state finance), see the Roadmap section of the plugin README. Unknown legacy key strings may still validate so older configs keep loading, but the runtime ignores them and the key-saving tools do not write roadmap keys.

How to obtain each key

apiDataGov

A free api.data.gov key covers api.congress.gov and api.fec.gov (and other federal APIs gated through the same gateway). Sign up at https://api.data.gov/signup/. The key is issued instantly and has a generous default rate limit.

googleCivic

Google Civic is part of Google Cloud's API set. You enable the "Google Civic Information API" in a Google Cloud project, then create an API key with that API allowed. Google Cloud's own documentation walks through the project creation, API enablement, and key restriction steps; the resulting key is what you save as googleCivic.

geocodio

Geocodio is a paid service with a free tier. Create an account on their site and copy the API key from the dashboard.

How to set keys

politiclaw_configure is an agent tool, not a shell command. Ask your agent to call it; use /politiclaw-setup if you need a copyable resume prompt.

politiclaw_configure writes keys into the gateway config in two situations:

• Pass any subset of keys directly (apiDataGov plus optional optionalApiKeys) for "save this one key" calls without re-running the full setup flow. Entries you do not provide are skipped.
• During onboarding, the api-key stage at the end of the wizard prompts for the same keys after address, stances, and monitoring cadence are saved.

Both paths trigger an OpenClaw gateway restart so the new credentials are picked up by the provider adapters. Onboarding fields (address, stances, monitoring mode) are persisted before the restart, and a checkpoint records the next setup stage. When the gateway comes back up, run /politiclaw-setup and continue from its prompt.

After saving, run /politiclaw-doctor to confirm the keys are in place and the dependent tools are healthy.

Practical setup order

1. Add apiDataGov first — most tools (bills, votes, finance) depend on it.
2. Add googleCivic if you want ballot tools (politiclaw_get_my_ballot, politiclaw_election_brief).
3. Add geocodio only if you prefer the API path for reps-by-address over the zero-key local shapefile path.
4. Run /politiclaw-doctor after any change.

Troubleshooting pointers

• If a bill, vote, or finance tool returns a missing-key error, see Troubleshooting → Bill, Vote, Or Finance Tools Are Unavailable.
• If a ballot tool reports Google Civic missing, see Troubleshooting → Ballot Tools Say Google Civic Is Missing.
• For the runtime status of any key (implemented, optional_upgrade, transport_pending), trust Generated Source Coverage over prose.