user

The User submodule handles the administrative side of user account management: creation, profile updates, avatar handling, role assignment, permission inspection, and identifier verification. It is intentionally separated from the Profile submodule, which handles self-service operations by authenticated users on their own accounts, enforcing the principle of least privilege at the API boundary.

Administrators holding the admin or admin-user role can create new accounts with a name, email, and initial password. Account updates allow changing the display name. Password resets set a new password on behalf of the user without requiring the current password, useful for locked-out accounts and onboarding flows where the initial credential must be reset immediately. Deletion via DELETE /user permanently removes accounts with no soft-delete option.

User avatars are stored via the File submodule. POST /user/:userId/avatar accepts a multipart image, stores it, and links the resulting File record to the user. The avatar is then publicly accessible at GET /user/avatar/:fileId without authentication, enabling embedding in email templates, public-facing profiles, and third-party integrations. Profile owners can also manage their own avatar through PUT /profile/avatar in the Profile submodule.

Role assignment can be managed from the user side: POST /user/:userId/role/:roleId assigns a single role and DELETE /user/:userId/role/:roleId revokes it. GET /user/:userId/role lists all roles currently held by a user. These endpoints complement the Role submodule's batch-replacement approach — both paths write to the same join table and can be used interchangeably.

The permission inspection endpoints GET /user/:userId/menu and GET /user/:userId/route return the effective set of menu entries and HTTP routes accessible to a specific user, computed from the union of all assigned roles. These are used by the admin panel to display an accurate summary of what a user can do without requiring the admin to manually union multiple role definitions.

User identifiers (email addresses) go through a verification flow by default. POST /user/:userId/verify-identifier/:identifierId allows admins to force-mark an identifier as verified, bypassing the email confirmation step. This is useful for seeding test users, migrating accounts from legacy systems, or resolving support escalations where the user cannot access the verification email.