Start
Authentication and keys
Sandbox and live keys, the Bearer header, and how to revoke a key.
Every request carries your key in one header. The REST API and the MCP server take the same key and the same header.
curl "https://data.heytownhall.com/v1/jurisdictions?limit=1" \
-H "Authorization: Bearer $HTD_KEY"Two kinds of key
| Key starts with | Environment | Reaches | Requests a minute |
|---|---|---|---|
htd_test_ | sandbox | The sandbox: Port Ellery, Marlow County and Tolland Township, fictional, in the live shapes. Free. | 10 |
htd_live_ | live | The live records. Billed per request. | 600 |
A sandbox key reads only the sandbox, and a live key reads only the live records. The prefix tells the API which one it has, and every answer says which with environment.
Getting a key
Sign-ups are not open yet. Keys come from the dashboard once sign-ups open. Until then you can read these guides and the reference, and plan your build against the sandbox shapes.
A live key needs a payment method on the account, and only an account owner can create one.
Live keys are not open yet. They open once the rates are final. Until then a card can be saved in the dashboard, and a request with a live key answers 403 with the code live_not_open. Sandbox keys work now.
A key is shown once
The dashboard shows a key's full value once, when you create it. After that it shows the prefix and the last four characters, such as htd_live_…a9Qz, so you can tell your keys apart. Copy the key into your secret store when you create it. If you lose it, create a new one and revoke the old one.
Keep keys on your server
Call the API from your server, not from a web page. The API sends no CORS headers, and a key in a page is a key anyone can read.
Revoke a key
Revoke a key in the dashboard as soon as you think it may have leaked, then create a new one. A revoked key can still answer for up to a minute in a data centre that had it, and then it answers 401.
When a key is refused
| Answer | Code | Why |
|---|---|---|
401 | unauthorized | No key, or not a valid one: unknown, revoked, or not a Hey Town Hall Data key. The answer carries WWW-Authenticate: Bearer. |
402 | billing_required | A live key with no payment method on file, or live keys paused for an unpaid invoice. |
Errors lists every code.