API keys

What a key can and can't do

Stated plainly, because you may end up pasting one into a public web page:

• Read-only. A key can fetch public data and your feed and subscriptions. It cannot change your account, post, subscribe, unsubscribe, or read anything else you own. Every mutation is rejected for key-authenticated requests.
• Yours, not anonymous. Requests made with your key act as you, so a feed widget shows the subjects you follow. If you want a neutral, public widget instead, use the iframe widgets — they need no key at all.
• Shown once. CivicGate stores only a SHA-256 hash of a key, never the key itself. The full value appears exactly once, when you create it. Lose it and you revoke it and make another — we genuinely cannot show it again.
• Revocable, and lockable to your domain. Revoking takes effect immediately. Set an allowed-origins list and browser requests from anywhere else are refused.

Create a key

1. Go to Account → API keys.
2. Give it a name that says where it will live ("my blog's sidebar").
3. Optionally list the origins allowed to use it — e.g. https://example.com, or .example.com to include subdomains.
4. Copy the key immediately. It is not shown again.

Use it — the widget bundle

Configure once; every CivicGate widget on the page picks it up.

<script src="https://www.civicgate.org/widget/civicgate-widget.js"></script>
<script>CivicGate.configure({ apiKey: "cg_live_…" })</script>

<!-- Your Following feed -->
<div data-civicgate-widget="feed" data-limit="10"></div>

<!-- One subject's public activity (no key needed) -->
<div data-civicgate-widget="subject" data-subject-type="bill" data-subject-id="hr-22-119"></div>

Use it — the iframe

No script at all. The key travels in the URL, so only use this on a page you control.

<iframe src="https://www.civicgate.org/embed/feed?key=cg_live_…&limit=10"
        width="100%" height="520" style="border:0" loading="lazy"
        title="CivicGate feed"></iframe>

Use it — the SDK

The same client the widgets use, for your own UI.

import { createClient, createFeedStore } from "@cg/sdk";

const cg = createClient({ apiKey: "cg_live_…" });

// One page of your feed, filtered and cursor-paged
const page = await cg.feed({ subjectGroups: ["bills", "people"], limit: 10 });
page.events.forEach(e => console.log(e.title, e.occurredAt));

// Or a self-refreshing store (instant paint, background refresh every ~12s)
const store = createFeedStore(cg, { refreshMs: 12000 });
store.subscribe(state => render(state.events));
store.start();

Filter vocabulary — subject types, event types, and groups — is discoverable via cg.catalog(), so you never hard-code a type string. Full field reference: API reference.

Limits

• Up to 20 active keys per account.
• Feed pages are 1–50 events; page with the nextCursor the API returns.
• The public API endpoint applies its own per-IP rate limit — see the API reference.