Users & roles management

The Users admin surface (Settings → Users) is where TENANT_ADMINs manage who has access to the tenant and what they can do.

Overview

You can:

• Invite new users (see Inviting your team)
• Change a user's role
• Assign or remove branch scope
• Reset a user's MFA device (for lost phones)
• Force-logout a user's active sessions
• Deactivate a user (revokes access; keeps historical audit trail)

You can NOT:

• Fully delete a user (breaks audit-log referential integrity). Deactivate is what you want.
• Change a user's email address (they create an account, you invite; if they need a new email, invite a new account).

Step-by-step — change a role

1. 1
   Go to Settings → Users. Filter the list by search or status if needed.
2. 2
   Click the user's row to open the detail panel.
3. 3
   In Role, pick the new role from the dropdown. See the Roles & Permissions Matrix for what each one grants.
4. 4
   Click Save. The change takes effect on the user's next login (or next request if they're currently active — middleware re-reads on every request).
5. 5
   If the change is security-critical (e.g. demoting a fired employee), click Force Logout to immediately terminate their sessions.

Step-by-step — reset someone's MFA

When a user loses their phone:

1. 1
   Confirm the user's identity out-of-band (don't rely on email alone — that's what the attacker would use).
2. 2
   Open the user's detail panel → Reset MFA.
3. 3
   Their existing authenticator is invalidated immediately; their next login goes through the MFA setup flow again.
4. 4
   The platform emails them a one-time setup code (so they don't need the old phone).
5. 5
   New backup codes are regenerated.

Branch scope

If your tenant has multiple branches, you can restrict a user to only their branch:

• Open user detail → Branch Scope → pick one or more branches, or leave empty for "all branches".
• A branch-scoped user sees only records (bookings, invoices, etc.) tagged to those branches.
• Admin roles (TENANT_ADMIN, ADMIN) ignore branch scope — they see everything.

Common pitfalls

Audit log

Every user change is recorded in Settings → Audit Log with the acting admin, timestamp, and before/after values. Filter by user_updated, user_invited, mfa_reset, user_deactivated for user-management activity.