Authentication
Authentication and plans
One key works across every layer, and what that key can see is governed by your plan's entitlements, including whether contact data is returned at all.
Authenticating a request
Send your key as a bearer token, remembering that keys are issued per environment and can be scoped to a subset of states or jurisdiction tiers.
curl https://api.civoren.com/v1/contests?state=AZ \
-H "Authorization: Bearer civ_live_7f3a…" \
-H "Civoren-Version: 2026-08-01"Entitlements
Three switches decide what a key returns, and they apply identically to every layer, so no surface can leak what another one withholds.
| Entitlement | Controls | Default |
|---|---|---|
contact | Campaign emails and phones, and campaign team contacts | Off |
geography | District boundary geometry and point-in-district resolution | On |
jurisdictions | Which tiers and states the key may read | All tiers |
Contact data is never returned by accident. Without the contact entitlement those fields are absent from the response shape entirely rather than nulled or redacted, and a query that names one is rejected rather than silently emptied, so you always know which outcome you got.
Plans
| Capability | Explore | Build | Enterprise |
|---|---|---|---|
| REST and GraphQL | Yes | Yes | Yes |
| Cypher | No | Yes | Yes |
| Agent endpoint | No | Yes | Yes |
| Webhooks | No | Yes | Yes |
| Bulk export | No | Monthly | On demand |
| Contact entitlement | No | Add-on | Add-on |
| Rate limit | 60 per minute | 600 per minute | Negotiated |
Rate limiting
Every response carries its own budget headers, and a 429 includes Retry-After in seconds.
Civoren-RateLimit-Limit: 600
Civoren-RateLimit-Remaining: 574
Civoren-RateLimit-Reset: 1786291200
Civoren-Entitlements: geography,jurisdictions