User Management

User Management is the administrative façade for the canonical user records of an instance. It is for system operators who need to inspect and maintain accounts; it is not a second identity store, an authentication-provider guide, or a self-service registration flow.

Start specimen This guide uses the Cabloy Start admin-user module to make the operational model concrete. An edition can compose the administration UI differently while keeping the same boundary between user facts, roles, departments, and backend authorization.

What User Management owns

A typical administrative User Resource lets a system administrator:

• list and search user accounts;
• view profile and account state;
• update permitted profile fields;
• activate accounts;
• change account status; and
• inspect the user's role and Department memberships.

The Start controller exposes this resource surface in vona/src/suite/cabloy-admin/modules/admin-user/src/controller/user.ts. Its management actions are individually protected with @Passport.systemAdmin():

@Web.put('account-status/:id')
@Passport.systemAdmin()
async setAccountStatus(...) {
  return await this.scope.service.user.setAccountStatus(...);
}

This guard is the authority boundary. A visible Admin menu or UI action does not authorize a direct request by itself.

User facts, role memberships, and Department memberships

A user record is one kind of fact. Role membership and Department membership are related but separate facts:

Fact	Answers	Owning administration flow
User profile	Who is this account?	User Management
Role membership	Which access groups does the user hold?	Role Management
Department membership	Which organizational units does the user belong to?	Department Management

The Start user-detail service deliberately projects all three so an operator can understand the account in one place. It does not make the User Resource the owner of every membership mutation.

A practical rule is: update account lifecycle in User Management; update an access grouping through Role Management; update organizational placement through Department Management.

Account lifecycle safeguards

Activation and account status are different concerns. Activation is generally part of bringing a registered account into service; account status controls whether an existing account can continue to use the system.

In the Start specimen, disabling an account has operational consequences beyond changing a field:

1. the service refuses an unsafe system-administrator transition;
2. permission state is cleared; and
3. active Passport sessions for the disabled user are evicted.

This protects against a stale signed-in session continuing with an old permission projection. It also illustrates why account-status changes belong in the backend service, rather than in a frontend-only switch.

Recommended operator workflow

Find user
  → inspect account, roles, and Departments
  → update profile or account lifecycle when appropriate
  → change role memberships in Role Management
  → change organizational memberships in Department Management
  → verify the affected user's refreshed access

When an operator changes a current user's access-related state, the relevant client should reacquire authoritative Passport, menu, and permission data. That refresh improves UX; the backend guards still enforce every request independently.

Boundaries to keep clear

• User Management is not an authentication-provider implementation. Read Auth Guide for sign-in providers and authentication flows.
• A user having a role does not automatically grant every API action. Action and data authorization are configured through RBAC Authorization.
• Seeing a menu does not authorize an API request. See Menu Authorization.
• User records are scoped to the active Vona instance; do not treat an administrative view as a cross-instance lookup surface.

Verification checklist

When implementing or adapting User Management, verify that:

1. every account-management endpoint has an explicit backend guard;
2. user detail can accurately distinguish account fields from role and Department memberships;
3. disabling a user invalidates permission/session state according to the active edition's policy;
4. protected administrator transitions cannot remove the final usable administrator; and
5. role and Department changes are made through their respective owners rather than duplicated in a user form.

Read next

• User Access Guide
• Auth Guide
• Role Management
• Department Management
• RBAC Authorization