vsmsconnect — API — users

← all endpoints

GET/api/v1/users auth: jwt (administrator | manage_users)

List all users belonging to the authenticated caller's business (businessId taken from the JWT, not the URL).

handlers: UsersController.list

Inputs

No parameters.

Outputs

200
APIResponseDataList<UserAdminDTO>
All users for the JWT's businessId. Includes totalRows.
POST/api/v1/users auth: jwt (administrator | manage_users)

Create a new user inside the caller's business. Argon2-hashes the password, derives username from the email local part, inserts into Users + UserRoles, and fires USER_CREATED + welcome email (fire-and-forget).

handlers: UsersController.create

Inputs

namerequireddefaultdescription
firstName body
string		yes—Given name (min 1 char).
lastName body
string		yes—Family name (min 1 char).
email body
string (email)		yes—Email address — must be globally unique.
roles body
UserRole[]		yes—At least one role from the UserRole enum.
password body
string		yes—Plaintext password (min 8 chars).

Outputs

201
APIResponseDataObject<UserAdminDTO>
Newly created user.
409
APIError
AUTH_EMAIL_TAKEN — email already registered.
422
APIError
VALIDATION_ERROR — schema violation.
PATCH/api/v1/users/:userId auth: jwt (administrator | manage_users)

Partial update of a user inside the caller's business. Patch may include roles, isActive, firstName, lastName, email, and/or password. Admin-removal safeguards prevent removing your own Administrator role or removing the last administrator. Fires USER_DEACTIVATED on isActive=false, USER_UPDATED otherwise.

handlers: UsersController.update

Inputs

namerequireddefaultdescription
userId path
uuid		yes—Target user UUID — must belong to the caller's business.
roles body
UserRole[]		no—Replacement role set (min 1).
isActive body
boolean		no—Activate/deactivate the user.
firstName body
string		no—Given name (min 1 char).
lastName body
string		no—Family name (min 1 char).
email body
string (email)		no—Replacement email address.
password body
string		no—Replacement password (min 8 chars, argon2-hashed server-side).

Outputs

200
APIResponseDataObject<UserAdminDTO>
Canonical post-update user record (re-fetched from the business set).
404
APIError
USER_NOT_FOUND — userId not in caller's business.
422
APIError
USER_CANNOT_REMOVE_OWN_ADMIN | USER_CANNOT_REMOVE_LAST_ADMIN | VALIDATION_ERROR (empty body or schema violation).