Organisations

One key for a group of venues: org keys, choosing the venue and listing what a key covers.

A company that runs several venues on Boozie can be grouped into an organisation. An organisation exists for the API only: back-office logins, menus and data stay one venue each. What it adds is the organisation key, one key that reaches several of the group's venues.

Boozie sets organisations up. Contact us with the venues to group and the owners who should be its admins. An admin must be an owner of one of the organisation's venues. A venue is in at most one organisation.

Org keys#

An organisation admin makes org keys in the back office: on Developers, the Organisation tab, under Organisation keys. They look like any key (bz_test_… / bz_live_…) and have scopes, a rate limit and an expiry in the same way. The rate limit is the key's, so every venue it reaches shares it. In addition, each key covers:

every venue of the organisation, including venues added later; or
a chosen list of its venues.

Org keys can't be bound to a host or hold hosts:read, so /hosts/me… answers 403 auth.scope_missing. For a host's own book, use a venue's host-bound key.

When the organisation changes#

A venue joins: keys that cover every venue reach it at once. Keys with a chosen list don't, until an admin adds it.
A venue leaves: no org key reaches it any more, and its owners stop being admins.
The organisation is deleted: all its keys are revoked.

Choosing the venue#

Every venue endpoint already names the venue in its path, so an org key picks the venue per request:

curl https://api-dev-799b.up.railway.app/public/v1/venues/2/bookings -H "Authorization: Bearer $ORG_KEY"
curl https://api-dev-799b.up.railway.app/public/v1/venues/5/bookings -H "Authorization: Bearer $ORG_KEY"

There is no Boozie-Venue header or any other: the {venueId} in the path is the only way to choose.

Listing what a key covers#

GET /venues works with any key or OAuth token and lists the venues it covers right now:

curl https://api-dev-799b.up.railway.app/public/v1/venues -H "Authorization: Bearer $ORG_KEY"

Each venue says whether its Developer access is on. Loop over this list rather than keeping your own, so that venues added to or removed from the organisation are picked up.

When a venue answers differently#

Answer	Why
`404 not_found`	The key doesn't cover the venue: it isn't in the organisation (any more), or isn't in the key's list.
`403 auth.developer_access_off`	The venue is covered, but Boozie has turned its Developer access off.
`403 auth.plan_feature`	The key holds the scope, but this venue's plan lacks the feature. Other venues still work.
`403 auth.scope_missing`	The key doesn't hold the scope at all.

Handle these per venue: one venue's 403 shouldn't stop your sync for the others.

Webhooks#

Webhook endpoints stay per venue. With webhooks:manage, an org key registers one at /venues/{venueId}/webhooks for each venue it covers. You may point them all at the same URL: every event carries its venueId.

Org keys or an OAuth app?#

Org key: you are the venue group, or its in-house developer, and one key for your own venues is enough.
OAuth app: you are a third party serving many unrelated venues. Each venue connects you and can disconnect you; an org admin can connect several of the group's venues in one go.