Authentication
One credential: an API key. How keys are owned, how to hold several, and how to rotate one without downtime.
Every request carries an API key, as a bearer token or in X-API-Key. There is exactly one kind of credential for this API. A web session cookie or a login token from the Boardwalk app is not one, and will not authenticate a /api/v1 request.
curl 'https://api.boardwalkai.com/api/v1/locations/states' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Key prefixes
| Prefix | What it is |
|---|---|
bwk_live_ | Production. Reads the real corpus and spends credits. |
bwk_test_ | Sandbox. Safe to put in a staging environment. |
csk_ | Issued before the Boardwalk rename. Still accepted, indefinitely. You do not need to migrate. |
The prefix is the only environment signal you need. There is no sandbox: true field on a record, and responses carry an X-Boardwalk-Environment header.
Keys belong to the team, and name the person
A key is held by the team and attributed to whoever created it. Two consequences worth designing for: a key keeps working when its creator leaves, and a team owner can see and revoke every key that can spend the team's credits. Usage is attributed to the key, so separate keys per service is a reasonable way to tell your integrations apart.
Rotating without downtime
- 1Mint a second, named key. You may hold several at once.
- 2Deploy it. The previous key keeps working during a 24-hour overlap.
- 3Revoke the old one once nothing is using it.
While a key is inside its rotation window its responses carry X-Boardwalk-Key-Rotating: true and a Warning header naming the moment it stops working — so a service that missed the rotation tells you before it breaks rather than after.
What the failures mean
| Response | Meaning | What to do |
|---|---|---|
401 missing_api_key | No credential reached us. | Check the header name and that the whole key was copied. |
401 unauthorized | The key did not resolve — revoked, or past its rotation grace window. | Mint a new one. |
402 subscription_required | The key is valid; the plan has lapsed. The key is not revoked. | Reactivate the plan. No redeploy, no re-issue. |
402 insufficient_credits | The key and plan are fine; the pool is empty for this request. | Narrow the query or top up. More here. |
Ready to make a call?
A free Boardwalk trial includes API access and a sandbox key. Counting, filtering, the location tree and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.