Map groups to door zones
Decide which groups open which physical zones, and know what reaches the cards already in people's wallets.
Owned by Admin · 8 steps · about 15 minutes
Why this exists
Zones are the bridge between "who you are" in the database and "which door opens" in the building. A reader is installed in a zone; a pass carries a list of zones; a scan is green only if the two overlap. Nothing about the person's groups is looked up at the reader — that would need a network the door does not have.
That last sentence is the whole design. The zone list is snapshotted into the signed pass when the pass is issued. Readers can therefore work offline and still be right, and a tampered payload fails signature verification instead of being trusted. The cost is that a pass is a photograph of your permissions at issue time, not a live query — so the platform re-issues passes whenever a grant changes.
The map change reaches existing cards, and it does it in the background. Changing a group's zones queues one pass refresh per active holder and a scheduled job re-mints them in batches — so a 4,000-member tier does not block the admin's request, and the audit row for the edit records how many cards were queued. Grant and revoke re-issue too; all three paths end in the same place.
This paragraph taught the opposite until 2026-08-29, describing a fan-out gap that plan 21 closed: it told an admin tightening zones for security to revoke and re-grant real people, which is an access interruption and an audit trail full of grants nobody meant. Corrected against the code — set_group_zones enqueues, rbac.pass_refresh drains.
Event ticket passes are not affected either way, and that is worth knowing before you go looking: a ticket's zones come from its tier, not from the holder's groups. The group-to-zone map governs membership cards.
Defaults ship sensible: member gets zone_a, vip_member gets zone_a and zone_b, and host, door_staff, venue_manager and admin get all three. Editing them is a full replace, not a merge, and every edit is audited.
Before you start
- An admin session — the zone editor and its API are admin-only.
- Somebody with a live membership pass to test against (vip@club.test has one).
Practise with
| Persona | Password | Note | |
|---|---|---|---|
| admin | admin@club.test | admin123 | the only persona that may edit the zone map |
| door_staff | door@club.test | door123 | sees the consequence at the reader |
| venue_manager | manager@club.test | manager123 | venue_manager implies door_staff, so it inherits door_staff's zones too |
Steps 1–3 — Admin
their manual →-
1Open the groups and zones editor and read the current map before changing it.Expected result One row per group with its zone codes and the implications spelled out.Watch out for The pseudo-group employee appears in the mapping data as a convenience for implication expansion. It is still not grantable to a person.
-
2Set the zone list for one group. Submit the complete list you want that group to end up with.Expected result The saved zone list comes back, and one audit row records old and new values.Watch out for This is a REPLACE, not an add. Send only zone_b and the group loses zone_a. Zone codes must match the simple lowercase pattern the endpoint enforces — a typo becomes a zone nobody has a reader in, and the failure shows up as a wrong-zone denial at a door, hours later.
-
3Probe the computed zones for one user, with and without an event id, before you trust the change.Expected result The union of that user's active grants. With no event id, scoped host grants contribute nothing at all.Watch out for That last part surprises people: a promoter's host zones only apply to their own event, so a bare probe legitimately shows fewer zones than you expect.
Steps 4 — Door Staff
their manual →The map decides which reader turns green for them and for the guests they scan.
-
4As a staff member, open your own passes and look at the zone list printed on the membership card.Expected result The zones you had when the card was issued.Watch out for If this does not match the map you just saved, the card predates your change. That is the documented gap, not a bug you can fix by refreshing the page.
Steps 5–6 — Admin
their manual →-
5Understand the re-issue rule: a grant, a revoke and a zone-map edit all re-issue the affected membership cards. The map edit does it in the background — one queued refresh per active holder, drained by the rbac.pass_refresh job in batches.Expected result The edit's audit row carries the number of cards queued, and the queue drains on the following ticks.Watch out for Corrected 2026-08-29: this step said a zone-map edit does NOT re-issue and told you to revoke and re-grant people to force one — an access interruption, and an audit trail full of grants nobody meant. Plan 21 closed that gap. What is still true is that a card is a photograph: between the edit and the drain a wallet carries the old zone set, so a tightening you need enforced this minute is a revoke, not a map edit.
-
6Open the access console and check which readers are installed in the zone you just changed.Expected result Readers with their zone assignment and status.Watch out for This page is one of the few admin surfaces a venue manager can also open. Reader token rotation and key rotation on it are still admin-only.
Steps 7 — Door Staff
their manual →The map decides which reader turns green for them and for the guests they scan.
-
7Scan a pass at a reader in a zone the holder does not have.Expected result A red result with the reason wrong_zone.Watch out for wrong_zone means the credential is genuine and the person is simply not allowed through this door. It is not a revoked pass and not a fake — do not treat it as fraud.
Steps 8 — Venue Manager
their manual →venue_manager implies door_staff, so its zone set is the union of both.
-
8Confirm the implication for yourself: a venue manager needs no separate door_staff grant to use the scanner.Expected result The scanner opens on a venue_manager grant alone.Watch out for Implication is one-way. door_staff does not imply venue_manager, and nothing implies admin.