Staff Management
Audience: Agency-success / Support / Management · Where in app: /agency/staff (list, create, edit) · Plan availability: Agency tier (verify specifics)
Staff management lets an agency owner invite team members into the agency portal and grant them a subset of capabilities. Staff are real users with user_type: 'agency_staff', scoped to one agency. There is no separate "roles" abstraction in the UI — access is controlled by a flat list of ten toggleable permissions per staff member. Only the agency owner can manage staff.
What it does
- Create a staff account with name, email, phone, password, and a set of permissions.
- List / edit / delete staff members.
- Toggle any of ten agency permissions per staff member.
- Migrate existing members from the agency's self-account company into agency staff (and the reverse: create a member account for a staff user) so one person can use both surfaces with one password.
How it works
Every staff endpoint first calls _verifyAgencyOwner: the caller must be user_type === 'agency' (the owner, not staff), and an agency must exist for them. So staff cannot manage other staff — staff management is owner-only by construction, independent of permissions.
A created staff user is user_type: 'agency_staff', linked to the agency via agency_id, parented to the owner (user_parent.parent_id), pre-verified, and assigned the generic member role record (the role carries no permissions — capabilities come from the permissions array). The owner always passes every permission check; staff are checked against their permissions array.
Permission enforcement is two-sided:
- Frontend:
appStore.agencyHasPermission(perm)returnstruefor the owner, else checksuser.permissions.includes(perm). TheAgencyPermissionGatecomponent overlays a "Permission Required" notice rather than hiding the screen. - Backend: controllers call
general_helper.hasAgencyPermission(user, perm)and return403if missing.
Source: frontend/src/views/agency/staff/ and backend/app/controllers/AgencyStaffController.js.
Configuration & options
The ten agency permissions
Defined in frontend/src/views/agency/staff/Create.vue (and Edit):
| Permission value | Label | Grants |
|---|---|---|
agency.view_dashboard | Dashboard | The agency dashboard sidebar entry |
agency.manage_clients | View Clients | All Clients list + detail (and Client Invitations when enabled) |
agency.manage_playground | Playground | Playground + Shareable Playgrounds (create, manage, share, email) |
agency.add_client_subscription | Add Client / Subscription | Create clients (standard/GHL), subscriptions, add-ons, cancel/reactivate, send activation invites |
agency.edit_clients | Edit Clients | PUT /agencies/companies/:id and client access (Agency Controls) |
agency.disable_clients | Disable Clients | Pause / resume (and archive/disable) client companies |
agency.impersonate_clients | Impersonate Clients | "Login as Owner" and agency setup sessions (owner-equivalent token) |
agency.subscription_payments | Subscription & Payments | Agency subscription, payment methods, wallet, wallet transfers (incl. the opening transfer on Add Client) |
agency.manage_packages | Manage Packages | Create/edit client packages & allocations (/agency/packages routes) |
agency.manage_settings | Agency Settings | Branding, white-label, GHL connect, partner listing, configuration |
Added 2026-09-10 (5ffd9f37, d10c15c4, backend b4a697fc7): view_dashboard, manage_clients and manage_playground turned three previously ungated sidebar sections into permissions (lets an owner create e.g. a playground-only staffer). Existing staff get all three from lib/agencySectionPermissionsBackfill.js; it was only reachable via the api-key /migrations route and never ran in prod, so pre-existing staff lost Dashboard and View Clients until it was exposed as a super-admin maintenance job (POST /admin/maintenance/agency-section-permissions, MigrationPanel card on Integrations Maintenance, dry-run first; one updateMany, runs inline — 5999e367c). The backfill only touches staff whose _id predates the gating release (GATING_RELEASED_AT = 2026-09-14 04:46 UTC, frontend main f43c87d0) — staff created after it had the toggles in front of their owner, so a missing section there was a choice (53e38ae8d). edit_clients split editing off the create permission; existing holders of add_client_subscription get it via the one-shot POST /migrations/backfill-agency-edit-clients (lib/agencyEditClientsBackfill.js, dry-run by default, optional agencyId), and until that has run everywhere AgencyController._canEditClients accepts either permission. The Settings entry itself is never gated (it hosts the staffer's own Profile); pages inside it check manage_settings.
Create staff (staff/Create.vue)
| Field | Required | Validation |
| ------------------------ | -------- | -------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
| Full Name (first_name) | yes | required | string |
| Email | yes | required | email; unique among agency/agency_staff (may reuse a member's email) |
| Phone | no | — |
| Password | yes | required | string | min:6 |
| Permissions | optional | array of the ten values; toggled in the side panel |
→ createStaffMember(data) → POST /agency/staff.
Client and playground assignment
0fb458768 (clients), 160532abc / frontend b6038910 (playgrounds). components/agency/StaffClientAssignment.vue sits under the Impersonate Clients and Playground toggles in Create/Edit: All clients / All playgrounds or Only selected.
Field (UserModel, agency staff) | Limits | Enforced in |
|---|---|---|
impersonate_client_ids | "Clients they can impersonate" — Login as Owner and setup sessions only; viewing/editing still follow the permissions | POST /user/:id/login (loginAs), POST /agencies/companies/:id/setup-session → 403 "This client is not assigned to you. Contact your agency owner." |
assigned_playground_ids | "Playgrounds they can manage" — every playground listed, only assigned ones writable | playground agency routes; list rows carry can_manage, others show View only with a lock |
Absent = everything (existing staff keep full access); [] = none; null in the request unsets the list. Pickers load from GET /agency/staff/assignable-clients / GET /agency/staff/assignable-playgrounds (owner only). A restricted staffer is auto-granted what they create. The agency's own workspace is never restricted. Frontend 2fa31852 stops the impersonation stack growing on own-site ⇄ portal switches.
Edit / delete
| Action | Repository fn | Endpoint |
|---|---|---|
| Load one | getStaffMember(id) | GET /agency/staff/:id |
| List | getStaffMembers() | GET /agency/staff |
| Update (name/phone/permissions/status/password) | updateStaffMember(id, data) | PUT /agency/staff/:id |
| Delete | deleteStaffMember(id) | DELETE /agency/staff/:id |
On update the backend emits a socket event user-data-updated to user:<staffId> so the staff member's live sessions refetch their permissions immediately.
Member ↔ staff migration
A person who is both a team member (inside the agency's self-account company) and an agency staff user is kept in sync via a bidirectional linked_user_id.
| Action | Repository fn | Endpoint | What it does |
|---|---|---|---|
| List eligible self-account members | getSelfAccountMembers() | GET /agency/staff/self-account-members | Members of the agency_self_account company, flagged already_linked |
| Migrate selected members → staff | migrateSelectedMembers(ids) | POST /agency/staff/migrate-selected | Clones each member into an agency_staff user (copies hashed password), links both ways; skips already-linked |
| Create a member for a staff user | createMemberForStaff(staffId) | POST /agency/staff/create-member | Creates the member counterpart in the self-account company and links it |
UI: staff/MigrateModal.vue.
Behaviors & edge cases
- Owner-only, always. Every staff route returns 403 to non-owner callers (
agency_staffincluded). Staff cannot create/edit/delete other staff regardless of permissions. - Email scoping. A staff email must be unique among agency/agency_staff users but may match an existing member email — that's how a person ends up linked across both surfaces. Auto-linking happens on create (
_autoLink). - Deleting a staff member unsets the linked member's
linked_user_idfirst, then removes the staff user (the linked member account remains). - Migration is idempotent. Already-linked members are skipped; if an
agency_staffalready exists for the email, the two are retroactively linked instead of duplicated. - Permissions are additive only. There's no "deny" — absence of a permission = no access. The owner is implicitly all-permissions.
- Bounce target is always openable. Every agency fallback redirect (forbidden permission, owner-only route,
/admin/*, login landing) goes throughrouter/agencyLanding.js: Dashboard ifview_dashboard, else Playground (manage_playground), else All Clients (manage_clients), else/agency/settings/profile(needs no permission). Redirecting toagency-dashboardunconditionally looped a staffer without Dashboard until Chrome killed the tab (b5bf85a8).router/redirectLoopAudit.test.jswalks every route × user profile, and the guard aborts any A→B→A cycle after 30 hops with anInfinite redirect in navigation guarderror (3e34543c). - Live permission changes. Because of the
user-data-updatedsocket emit, a staff member sees permission changes without re-logging in.
Plan & limits
- No documented cap on staff count (verify whether the agency tier limits seats).
- Staff are part of the agency portal tier; they don't consume client sub-account slots.
Technical implementation
- Views:
frontend/src/views/agency/staff/{List,Create,Edit,MigrateModal}.vue - Routes:
frontend/src/router/agency.js(agency-staff,-create,-edit) - Repository:
frontend/src/repositories/agency/staff.js - Controller:
backend/app/controllers/AgencyStaffController.js— see backend service - Permission helpers:
appStore.agencyHasPermission(frontend/src/store/app.js),general_helper.hasAgencyPermission(backend),components/agency/AgencyPermissionGate.vue - Model: users with
user_type: 'agency_staff', fieldsagency_id,permissions[],linked_user_id(UserModel)