Skip to main content

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) returns true for the owner, else checks user.permissions.includes(perm). The AgencyPermissionGate component overlays a "Permission Required" notice rather than hiding the screen.
  • Backend: controllers call general_helper.hasAgencyPermission(user, perm) and return 403 if 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 valueLabelGrants
agency.view_dashboardDashboardThe agency dashboard sidebar entry
agency.manage_clientsView ClientsAll Clients list + detail (and Client Invitations when enabled)
agency.manage_playgroundPlaygroundPlayground + Shareable Playgrounds (create, manage, share, email)
agency.add_client_subscriptionAdd Client / SubscriptionCreate clients (standard/GHL), subscriptions, add-ons, cancel/reactivate, send activation invites
agency.edit_clientsEdit ClientsPUT /agencies/companies/:id and client access (Agency Controls)
agency.disable_clientsDisable ClientsPause / resume (and archive/disable) client companies
agency.impersonate_clientsImpersonate Clients"Login as Owner" and agency setup sessions (owner-equivalent token)
agency.subscription_paymentsSubscription & PaymentsAgency subscription, payment methods, wallet, wallet transfers (incl. the opening transfer on Add Client)
agency.manage_packagesManage PackagesCreate/edit client packages & allocations (/agency/packages routes)
agency.manage_settingsAgency SettingsBranding, 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)LimitsEnforced in
impersonate_client_ids"Clients they can impersonate" — Login as Owner and setup sessions only; viewing/editing still follow the permissionsPOST /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 writableplayground 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​

ActionRepository fnEndpoint
Load onegetStaffMember(id)GET /agency/staff/:id
ListgetStaffMembers()GET /agency/staff
Update (name/phone/permissions/status/password)updateStaffMember(id, data)PUT /agency/staff/:id
DeletedeleteStaffMember(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.

ActionRepository fnEndpointWhat it does
List eligible self-account membersgetSelfAccountMembers()GET /agency/staff/self-account-membersMembers of the agency_self_account company, flagged already_linked
Migrate selected members → staffmigrateSelectedMembers(ids)POST /agency/staff/migrate-selectedClones each member into an agency_staff user (copies hashed password), links both ways; skips already-linked
Create a member for a staff usercreateMemberForStaff(staffId)POST /agency/staff/create-memberCreates 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_staff included). 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_id first, then removes the staff user (the linked member account remains).
  • Migration is idempotent. Already-linked members are skipped; if an agency_staff already 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 through router/agencyLanding.js: Dashboard if view_dashboard, else Playground (manage_playground), else All Clients (manage_clients), else /agency/settings/profile (needs no permission). Redirecting to agency-dashboard unconditionally looped a staffer without Dashboard until Chrome killed the tab (b5bf85a8). router/redirectLoopAudit.test.js walks every route × user profile, and the guard aborts any A→B→A cycle after 30 hops with an Infinite redirect in navigation guard error (3e34543c).
  • Live permission changes. Because of the user-data-updated socket 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', fields agency_id, permissions[], linked_user_id (UserModel)