Roles & permissions
How roles work in your community: the two-layer model (admin capabilities + community participation), the Resident built-in, and how to onboard staff who shouldn't appear in resident surfaces.
On this page
The two-layer model
Permissions in this platform are stored on roles, not on accounts directly. A role bundles capabilities and a community assigns roles to specific people. Two separate categories of capabilities live on each role:
Admin permissions — what someone can do on the management side of the portal. Ten modules: members, dues, financials, architectural reviews, violations, maintenance, announcements, chat moderation, documents, and site settings. Each module has three cumulative levels: view, edit, and admin. A Treasurer role might grant finance/admin + dues/admin + users/view and nothing else.
Community participation — what someone can do on the resident side: post in chat, vote in polls, RSVP to events, submit maintenance and architectural requests, list in the marketplace, recommend vendors, register pets, browse the directory. Each capability is a simple on/off toggle. The Resident built-in role grants all twelve by default.
Most people in a community get the Resident role (full participation, no admin grants). A volunteer treasurer gets Resident + Treasurer. A property-management employee who runs the system but doesn't live in the community gets Community Admin + nothing on the participation side — they can manage dues and approve residents, but they don't appear in the directory and can't RSVP to the block party.
The Resident role
Every approved community member gets the Resident role automatically. The role lives in the role library at /admin/roles alongside the other built-ins; communities can edit its participation grants in place to change baseline policy for everyone at once.
For example, if you want to disable resident-created polls community-wide (so only the board can start polls), open the Resident role and toggle off the vote_polls capability... wait, actually that disables voting, not creating. Creating polls is gated separately. The point is: editing the role propagates to every resident on next page load.
Admin scoped roles
Five built-in admin roles ship with sensible default grants and can be edited in place, cloned, or disabled per community:
Treasurer. Dues + Financials at admin level. View-only on members and documents.
ARC Chair. Architectural reviews at admin level. View-only on members and documents; can also edit announcements.
Social Chair. Announcements + calendar at admin level. View-only on members and documents.
Moderator. Chat moderation at admin level. View-only on announcements and members.
Maintenance Liaison. Maintenance at admin level. View-only on arch reviews, members, and documents.
Two system roles also exist — Sys Admin and Community Admin — but those are platform-level and only assigned via the legacy account_type flag, not the regular role assignment drawer.
Onboarding staff (non-residents)
Property-management employees, off-site board members, and other staff need admin access without resident participation. Two paths get them there:
From pending approval: on /admin/users, the sibling Approve as staff button next to the regular Approve. Both run the same approval, but the staff path skips the auto-assignment of the Resident role. The new staff member lands approved with no participation grants; assign their admin scoped role next.
For an existing user: open their profile → Roles tab. To remove resident participation, revoke the Resident role assignment (X button on the row). To grant it back later, use the prominent Grant resident access button at the top of the section.
Custom roles
Clone any built-in role to create a custom variant. Common patterns:
"Limited Resident" — clone Resident, untick all participation grants except chat_post. Assign to staff who need chat access for emergency outreach but shouldn't appear in other resident surfaces.
"Resident with Polls" — clone Resident, enable a poll-creation capability (if your community wants to delegate poll authorship to all residents rather than only the board). Mark it is_default_for_new_residents=true and the approval flow assigns it instead of (or alongside) the base Resident role.
"Pool Committee" — start from scratch. Maybe just announce/edit + chat/admin on a single channel. Assign to chairs who coordinate pool scheduling but don't need broader access.
Audit trail
Every change to a role or assignment writes to role_change_event. Editing the Resident role's participation grants logs separately from editing its admin grants (so the timeline distinguishes "policy change" from "matrix tweak"). Auto-assignments at approval time tag with source=approval_auto_assign so the audit reads as "Sarah was assigned Resident automatically at approval" rather than "Mark assigned Resident to Sarah."
Revocations soft-delete (the row sticks around with a revoked_at timestamp). Re- assigning after a revocation creates a new row, so the full history of "who was treasurer in 2024 vs 2025" survives indefinitely.