Cloud — User API

Base path: /api/cloud/user
All endpoints use POST. SuperAdmin authorization required unless noted otherwise.

Manages the user lifecycle within the HR Studio platform: create, update, soft-delete, restore, and admin password reset.

---

POST /api/cloud/user/create

Creates a new user under an existing tenant.

Auth: SuperAdmin.

Request

Field	Type	Required	Note
email	string	yes	Max 255 characters; must be unique across all users
password	string	yes	Must pass the active password policy
userTypeId	short	yes	2 = TenantAdmin. Value 1 (SuperAdmin) is reserved and rejected
tenantId	UUID	yes	Public UUID (ten_uuid) of the target tenant
languageId	short?	no	Defaults to 1 (Italian) if omitted
firstName	string?	no	Max 255 characters
lastName	string?	no	Max 255 characters

Response 201 Created

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "userTypeId": 2,
  "tenantId": "8c4e1a92-1234-4abc-9def-000000000001"
}

Errors

Status	Condition
404	Target tenant not found or deleted
409	Email already registered
422	Password fails complexity rules; or userTypeId = 1

---

POST /api/cloud/user/update

Updates mutable fields of an existing user. All fields are optional — omit any field to leave it unchanged.

Auth: SuperAdmin.

Request

Field	Type	Required	Note
userId	UUID	yes	ID of the user to update
email	string?	no	New email; must be unique if provided
firstName	string?	no	Max 255 characters
lastName	string?	no	Max 255 characters
languageId	short?	no	Language preference
statusCode	short?	no	1 = active, 2 = suspended

Response 200

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "updated@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "languageId": 1,
  "statusCode": 1,
  "updatedAt": "2026-04-29T10:00:00Z"
}

Errors

Status	Condition
404	User not found
409	New email already in use by another user

---

POST /api/cloud/user/delete

Soft-deletes a user. The record is retained in the database with usr_deleted = true. The user cannot log in after deletion.

Auth: SuperAdmin.

Request

Field	Type	Required
userId	UUID	yes

Response 204 No Content

Errors

Status	Condition
404	User not found
409	User is already deleted

---

POST /api/cloud/user/undelete

Restores a soft-deleted user, allowing them to log in again.

Auth: SuperAdmin.

Request

Field	Type	Required
userId	UUID	yes

Response 204 No Content

Errors

Status	Condition
404	User not found
409	User is not currently deleted

---

POST /api/cloud/user/password/reset

Admin operation to reset a user's password. Sets a 7-day forced expiry so the user must change the password on next login (mustChangePassword = true).

Auth: SuperAdmin or TenantAdmin. TenantAdmin can only reset users within their own tenant.

Request

Field	Type	Required	Note
userId	UUID	yes	Target user
newPassword	string?	no	If omitted, a random compliant password is auto-generated and returned in the response

Response 200

{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "user@example.com",
  "generatedPassword": "Xk9#mPq2Lv"
}

Field	Description
userId	User ID
email	User email
generatedPassword	Populated only when newPassword was omitted. Deliver to the user out-of-band (e.g. by email). null when caller provided an explicit password

Errors

Status	Condition
400	Explicit newPassword fails complexity rules
403	TenantAdmin attempting to reset a user outside their own tenant
404	User not found