Authentication

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

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. First: a key survives its creator's departure once a team owner reassigns it — Settings → API → reassign keeps the secret, the id and your deployed configuration exactly as they are and changes only the attributed actor. Reassignment is the step that makes the key team-owned in practice; if the creator's account is closed while the key is still attributed to them, the key stops authenticating. Second: a team owner can see and revoke every key that can spend the team's credits.

A key also carries the membership of the user who created it: what the alerts and lists routes show is that user's own entities plus what teammates have shared with them, and mutations are attributed to that user. On a team, create one key per member rather than passing one key around. The credit pool is shared either way.

How many keys you may hold

You may hold 2 active live keys per user at once, on every plan. Creating one more than that is refused. Rotation does not count against the ceiling. The replacement and its predecessor coexist for the grace window below. If you want a key per service, create one per team member instead: the ceiling is per user and the credit pool is shared either way. (Test-prefix keys have their own allowance of 10, for a sandbox that is not serving data yet.)

Rotating without downtime

1. 1Rotate the key — Settings → API, or POST /api/user/api-keys/{id}/rotate. The replacement is issued immediately and the predecessor keeps authenticating for the grace window you choose: 1, 24, 168 hours, defaulting to 24.
2. 2Deploy the replacement inside that window.
3. 3Nothing to revoke — the predecessor retires itself when the grace ends.

Minting a second key is not rotating: it starts no grace window at all, and the old key keeps working indefinitely until you revoke it by hand. Only rotation sets a deadline.

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