A member of hospitality or venue staff can register themselves, ends up bound to the one venue they work at, and sees the experiences that are live at that venue. They are operators, not publishers: no Perforce access, no library developer record, and no first experience of their own.
This is the sibling of the hydramancer self-start flow in #763, for the other audience.
Verified first-hand while building #763 on 2026-10-02.
| Piece | State | Use here |
|---|---|---|
iamnim POST /api/me/join |
live in iamnim v0.51.0, gated on the self_join_orgs allow-list |
the self-join mechanism, but see the design problem below |
hydravenues organization_id per venue |
live, read needs no credential | how venue access is derived today |
library GET /api/v1/experiences/live?district=&venue= |
live | the "relevant experiences" list, once a venue is known |
hydramancer sign-in plus /register, /register/start, /register/done, /studio |
live in hydramancer v0.4.0 | the working shape to copy |
Two properties of the platform matter for this feature, and both are already true:
The library requires an exact venue match whenever a venue is supplied. An empty venue list on an experience does not act as a wildcard. Bodies always supply a venue, so an experience is only visible at a venue that names it.
hydracluster's eligible-bodies endpoint drops a body unless its venue matches the head's venue, or the two share an owner. Venue is therefore already a hard filter at the streaming layer, not only in the catalogue.
Access today is per organization, not per venue. That is the whole difficulty, and it is why this feature is not a copy of #763 with the labels changed.
visit-flanders owns three venues: cloud-seven, rupelmonde and sint-niklaas-tourism-office. A staff member who works at Rupelmonde would have to join visit-flanders to get any venue at all, and would then see all three. That is wrong for hospitality staff, who should see one venue.
Self-joining also cannot be opened the way it is for hydramancers. The self_join_orgs allow-list is the entire authorization, so adding visit-flanders to it would let anyone on the internet join a real customer organization. The allow-list is safe precisely because hydramancers is meant to be open.
So this feature needs a venue-scoped binding that does not exist yet. Options, none of them decided:
A per-venue invite or join code. A code, or a QR displayed at the venue, carrying a venue-scoped token. Registration consumes it and binds the person to that one venue. Cheapest to reason about, and it matches how staff actually arrive, which is physically on site. Costs a new token-issuing and token-redeeming surface, and a decision about expiry, reuse and revocation. It also keeps real customer organizations closed, which is its main attraction.
A per-venue membership concept. Venue membership becomes a first-class record, either in hydravenues next to organization_id or in Pantheon alongside organization membership. Conceptually the cleanest, because "this person works at this venue" is a real fact the platform currently cannot express. Costs a schema and an API in whichever service owns it, plus a decision about whether venue membership implies organization membership or is independent of it. Pantheon is the system of record for organizations, so putting it there keeps identity in one place, at the price of changing a service that every org depends on.
Organization membership plus a venue attribute on the person. Join the owning organization, then narrow the view with a stored preference or assignment. Smallest change, and the weakest: the narrowing is presentation only, so the person still holds organization-level access underneath. Not suitable if staff must be genuinely confined to one venue.
The choice is the owner's. It should be made before any code, because the rest of the flow hangs off it.
View only, or also launch? Seeing the experiences live at a venue is one capability. Starting a session on a head at that venue is another, and considerably more powerful. The streaming layer already filters by venue, so launching is technically within reach, but it is a separate decision.
Do venues need staff roles? One level may be enough to start. A venue manager who can see more than a bartender is a second level, and worth deciding early because it is hard to retrofit.
What happens when someone leaves? A binding that cannot be revoked is a liability. Whichever option above is chosen has to answer this, and a join code that stays valid forever answers it badly.
What can be copied from the hydramancer flow:
The sign-in handoff to iamnim with a redirect_uri, the session cookie, and the idempotent onboarding step that runs on return. The page shape of /register and /studio. The principle that identity writes stay in iamnim and the portal holds no identity credential.
What cannot be copied:
The authorization model. #763 works because hydramancers is an open organization that exists to be joined by anyone, and because venue access follows from owning the venue. Neither holds for hospitality staff at a customer venue. The Perforce provisioning, the library developer record and the first experience are all publisher concerns and have no place in this flow.