Client Settings — Implemented Spec

Last updated: 2026-05-04 Status: Core pages live (✅ Profile, Team, Channels, Billing); Notifications/Security/API Access planned.

Overview

The client settings area (/client/settings/*) provides workspace configuration for all client org roles. It is role-gated: what you see in the sidebar and what you can do depends on your workspace role.

---

Workspace Roles

humanwork uses a 4-tier role model (Slack-inspired):

Role	DB Value	Description
Owner	owner	One per org. Created when the client admin accepts the onboarding invite. Full control. Can transfer ownership. Cannot be removed — only via ownership transfer.
Admin	admin	Can invite/remove members, change roles (up to Admin), manage channels, manage billing.
Billing	billing	View/manage billing only. For CFOs and finance team. Cannot invite or manage channels.
Member	member	Default role. Can use chat. Can view team list (read-only). Cannot manage anything.

Role Permissions Matrix

Section	Member	Billing	Admin	Owner
Profile (edit own)	✅	✅	✅	✅
Team (view)	✅	✅	✅	✅
Team (invite/remove/change roles)	❌	❌	✅	✅
Team (transfer ownership)	❌	❌	❌	✅
Channels	❌	❌	✅	✅
Billing	❌	✅	✅	✅

---

Settings Navigation

The sidebar shows/hides items based on orgRole from the JWT:

Profile      → always visible
Team         → always visible (read-only for Member/Billing)
Channels     → Owner, Admin only
Billing      → Owner, Admin, Billing only

---

Pages

/client/settings/profile

• Edit display name, avatar, phone, title, bio
• All roles

/client/settings/team

• View all workspace members: Avatar | Name | Email | Role badge | Joined date
• Role badges: Owner (gold), Admin (blue), Billing (purple), Member (gray)
• Admin/Owner only: "+ Invite Member" button, role change dropdown per row, "Remove" button
• Owner row: no actions (immune to removal; role only changes via transfer-ownership)
• Self row: highlighted, "(you)" label, no remove button
• Cannot demote the only Admin/Owner (guard enforced client-side + server-side)
• Owner-only section (bottom): Transfer Ownership modal → select new owner from existing members
• Non-owner section (bottom): Leave Workspace (stub — contact admin to implement)

/client/settings/channels

• Admin/Owner only
• Manage WhatsApp/email/Slack channel connections
• (Phase 2 — stub placeholder for now)

/client/settings/billing

• Owner, Admin, Billing roles
• View plan, usage, renewal date
• Manage payment method

---

API Endpoints Used

Action	Method	Endpoint	Auth
List members	GET	/admin/members	org_admin, superadmin
Invite member	POST	/admin/members/invite	org_admin, superadmin
Change member role	PATCH	/admin/members/:id/role	org_admin, superadmin
Remove member	DELETE	/orgs/:orgId/members/:userId	OrgRolesGuard("admin")
Transfer ownership	POST	/orgs/:orgId/transfer-ownership	OrgRolesGuard("owner")

---

Role Derivation

• orgRole is stored in org_memberships.org_role (TypeORM: OrgMembership.orgRole)
• Valid values: "owner" | "admin" | "member" | "billing" (TypeScript: OrgRole type)
• JWT payload: orgMemberships[0].orgRole
• platformRole for client users: "client_admin" (when orgRole=admin|owner) or "client_member" — see CLAUDE.md role table. (Legacy org_admin / org_member strings remain readable for back-compat; new code/UX copy uses client_*.)

---

/client/settings/notifications (planned)

• Notification preferences: email digest frequency (immediate / daily / weekly / off), browser push opt-in.
• All roles.
• Planned — UI stub; no dedicated endpoint yet (preferences stored on User entity in future iteration).
• Cross-ref: The in-app notification feed itself (the NotificationBell dropdown + /v1/notifications API) shipped via #915 (AppNotification entity + WS push). The settings page below controls delivery channels / digest cadence for that feed; the feed UI is already live for all roles.

/client/settings/security (planned)

• Change password, active sessions list, revoke sessions.
• 2FA setup (TOTP via otplib — API already supports POST /auth/2fa/setup + POST /auth/2fa/verify).
• All roles.
• Planned — API endpoints exist; settings page not yet built.

/client/settings/api-access (planned)

• View and manage API keys / webhook secrets for the org's integration.
• Admin, Owner only.
• Planned — Future; requires API key management endpoints.

---

Full Settings Suite

Page	Route	Roles	Status
Profile	/client/settings/profile	All	✅ Live
Team	/client/settings/team	All (manage: Admin/Owner)	✅ Live
Channels	/client/settings/channels	Admin, Owner	✅ Live
Billing	/client/settings/billing	Admin, Owner, Billing	✅ Live
Notifications	/client/settings/notifications	All	🔮 Planned
Security	/client/settings/security	All	🔮 Planned
API Access	/client/settings/api-access	Admin, Owner	🔮 Planned

---

Navigation Rules

The settings sidebar is role-gated:

Profile        → always visible (all roles)
Team           → always visible (read-only for Member/Billing)
Channels       → Owner, Admin only
Billing        → Owner, Admin, Billing only
Notifications  → all roles (planned)
Security       → all roles (planned)
API Access     → Owner, Admin only (planned)

Route guard: if a lower-privileged role navigates directly to a hidden route (e.g., /client/settings/channels), the settings layout redirects to /client/settings/profile.

---

Future Work

• Leave workspace API — DELETE /orgs/:orgId/members/:userId for self-removal (currently only admins can remove others; self-removal not implemented)
• Resend invite — allow admins to resend pending invites
• Revoke invite — allow admins to cancel pending invites