DevelopersGetting startedConcept
Authentication and permissions
How API keys authenticate, what each key permission allows, and how your plan's quota and rate limit apply.
Every request to the CapitolMath API carries an API key. The key says which organization is asking, and through that organization, what the request may reach: the organization's plan sets the limits, and the key's own permissions say what kind of call it may make.
Bearer keys#
Send the key in the Authorization header as a bearer token:
Authorization: Bearer vd_live_…
An X-Api-Key: vd_live_… header works too, for tools that can't set Authorization. A request without a key, or with one that's wrong or revoked, gets 401 unauthorized — deliberately without saying which, so a guessed key learns nothing.
A key is shown once, when it's created; CapitolMath stores only a hash of it. If you lose one, revoke it and create another.
Who holds keys#
Only members with a Full license create keys — Owners and Admins included — on their My profile page; see Creating an API key. Keys spend the organization's quota, but each acts as the person who created it, so an integration should use a key created by someone who'll stay: when they leave, their keys stop.
A key is revoked:
- by its creator, or by any Owner or Admin from Organization → API keys;
- automatically, when its creator's license is changed from Full to Basic — so a member with a Basic license never holds a working key;
- automatically, when its creator is removed from the organization or leaves it. Keys are never handed to someone else, because a key carries its creator's access.
A key acts as the member who created it where that matters: the saved-view endpoints run only the views that person can see — their own and those shared with them — and /v1/tracked-items returns only the tracked items they can see, through their permissions as they stand on each call. The MCP server reads tracked items through the same route, so an assistant sees exactly what the key's creator sees.
Key permissions#
Each key holds one or more permissions, chosen under This key may when it's created. Give a key only what the tool using it needs.
| Permission | What it allows |
|---|---|
| Read the API | Bills, votes, officials, events and the rest of /v1. |
| Download bulk datasets | Links to the nightly dataset files, where your plan includes them. |
| Read the audit log | The organization's audit log, by id, from GET /v1/audit-events. Only an Owner or Admin can give a key this, and only on a plan that includes it. |
| Change tracked items | Track bills (POST /v1/tracked-items) and change their fields (PATCH /v1/tracked-items/{id}), as the key's creator could in the app. Only someone who can track bills or change tracked items can give a key this, and every change is checked against their permissions as they stand when it's made. A key with only this permission is answered with the item's id and what changed, never the item. |
A new key starts with the first two. A request a key isn't permitted to make gets 403 forbidden, naming the permission it lacks. If a key's creator stops being an Owner or Admin, the key loses Read the audit log; if they can no longer change tracked items, or have an email change waiting for confirmation, its changes are refused with the reason. See The audit log.
What your plan decides#
Every key in an organization draws on the same plan, whichever member created it:
- Monthly quota. One pool of calls a month for the whole organization, counted per UTC calendar month. Every request served counts, including ones that fail with a
4xx; requests refused for being over the quota don't. - Rate limit. Requests a minute, again shared by all the organization's keys. Hitting it doesn't use quota.
- Page size. How many records a list page can return.
- Analysis. Without CapitolMath's analysis in your plan, its fields — political lean, the bipartisan index, sponsor effectiveness — come back
nullrather than disappearing, and the response carriesX-Analysis: not-included. Endpoints that are nothing but analysis, such as whip counts, and filters by political lean, return403 forbidden. - Jurisdictions. On the State plan, keys reach only the state the plan covers: naming any other jurisdiction,
USincluded, returns403 forbidden, and leaving an optionallocationout means that state.
See Plans and what they include for each plan's figures.
Quotas and rate limits#
Each response reports where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit, X-RateLimit-Remaining | Requests allowed this minute, and how many are left |
X-RateLimit-Reset | When the minute resets, in epoch seconds |
X-Quota-Limit, X-Quota-Remaining | The month's quota, and how much is left (unlimited where it is) |
X-Quota-Period | The month being counted, as YYYY-MM |
Going over either returns 429: rate_limited, with a Retry-After header saying how many seconds to wait, or quota_exceeded, which lasts until the next month. The organization's Owners and Admins, and everyone holding an active key, are emailed when usage reaches 80% of the quota and again at 100%. Owners and Admins can see who is using it under Organization → API usage, counted by who created each key.