Integration keys

Getting a key

There is no public sign-up. A venue group’s admin creates integration keys in their admin under Admin, Integrations, Integration keys, and gives you the key together with your base URL. Agents the venue group sets up in Kwickblocks get their own agent-owned keys in the same place.

A key is shown once, when it is created or rotated. Only a salted hash is kept, so a lost key can’t be shown again: ask for it to be rotated.

Live and sandbox

Key prefix	Reaches
kb_ik_live_…	The venue group’s live bookings.
kb_ik_sandbox_…	A separate sandbox database. Sandbox writes never touch live data, and sandbox bookings send no texts or emails.

Build and test against a sandbox key, then switch to a live key.

Capabilities

A key carries one or more capability groups. An operation the key’s groups don’t include answers 403 capability-missing, and the MCP server leaves that tool out of the key’s tool list.

Capability	Name	Allows
content.read	Read content	Venues, opening hours, menus, events and knowledge content.
bookings.create	Check availability & book	Check availability and make bookings.
bookings.manage	Find & change bookings	Find a booking by its reference and phone number, then change, cancel or mark it running late.
payments.send-link	Send payment links	Text a guest the link to pay a deposit.
enquiries.create	Submit enquiries	Send an enquiry to the venue team.

Venue scope

A key covers one venue, several venues, or every venue in the group.

• One venue: that venue is implied, so venueId is optional.
• Several venues: send venueId; without it the answer is 400 venue-required.
• A venue the key doesn’t cover: 404 venue-not-found, exactly as if it didn’t exist.

Rotation and revocation

• Rotate issues a new key. The old key keeps working for 48 hours, so you can switch over without downtime.
• Revoke stops a key at once.
• A key can also have an expiry date set by the admin.

A revoked, expired or unknown key answers 401 invalid-key with WWW-Authenticate: Bearer.

Rate limits

Each key has its own limit, by default 100 requests a minute with bursts of 20; the admin can change it. Over the limit the answer is 429 rate-limited with a Retry-After header in seconds. Wait that long before retrying.

Idempotency

• REST: every POST needs an Idempotency-Key header (any unique string, such as a UUID). Retrying with the same key and the same body returns the first answer and does nothing twice. The same key with a different body is 409 idempotency-conflict.
• MCP: tools that write accept an optional idempotencyKey. Without one, an identical call from the same key within 10 minutes returns the first answer.