Users Module

Overview

Swagger-driven developer documentation for user management endpoints and contracts.

Key APIs

Method	Path	Summary
GET	`/api/users`	List users
POST	`/api/users`	Create user
DELETE	`/api/users/{userId}`	Delete user
GET	`/api/users/{userId}`	Get user details
PATCH	`/api/users/{userId}`	Update user

Frontend Usage Flow

Frontend list pages call collection GET endpoints to load tables or summary views.
Detail pages call parameterized GET endpoints to load a single resource before rendering tabs, forms, or detail sections.
Create forms submit payloads to POST endpoints and then refresh the list or navigate to the created resource.
Edit flows load existing values, submit to PUT or PATCH endpoints, and then refresh the visible state.
Delete actions call DELETE endpoints and then refresh collection state.

GET `/api/users`

Summary: List users

Operation ID: UsersController_listUsers

Tags: Users

Security:

bearer

Responses

200

Users returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/UserResponseDto"
  }
}

Example:

json

[
  {
    "userId": "user-123",
    "fullName": "John Doe",
    "email": "john@example.com",
    "role": "TENANT_ADMIN",
    "status": "ACTIVE",
    "isProtected": false,
    "notificationsEmailEnabled": true,
    "notificationsMessagingEnabled": false,
    "notificationPhone": "+919876543210",
    "notificationEscalationLevel": 1,
    "notificationSeverities": [
      "WARNING",
      "MINOR",
      "MAJOR",
      "CRITICAL"
    ],
    "notifyOnAlarmCreated": true,
    "notifyOnAlarmEscalated": true,
    "notifyOnAlarmCleared": true,
    "canAcknowledgeAlarms": true,
    "hasGlobalAssetAccess": true,
    "hasGlobalDeviceAccess": true,
    "assetCount": 3,
    "deviceCount": 5,
    "assetIds": [
      "asset-1",
      "asset-2"
    ],
    "deviceIds": [
      "device-1",
      "device-2"
    ],
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:30:00.000Z"
  }
]

401

Unauthorized

No response body.

Notes / Constraints

Swagger declares security requirements for this operation.

POST `/api/users`

Summary: Create user

Operation ID: UsersController_createUser

Tags: Users

Security:

bearer

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "fullName",
    "email",
    "role"
  ],
  "properties": {
    "fullName": {
      "type": "string",
      "description": "Full name of the user"
    },
    "email": {
      "type": "string",
      "description": "User email address"
    },
    "role": {
      "type": "string",
      "description": "User role",
      "enum": [
        "TENANT_OWNER",
        "TENANT_ADMIN",
        "TENANT_RW",
        "TENANT_READ_ONLY"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "DISABLED"
      ]
    },
    "notificationsEmailEnabled": {
      "type": "boolean"
    },
    "notificationsMessagingEnabled": {
      "type": "boolean"
    },
    "notificationPhone": {
      "type": "string"
    },
    "notificationEscalationLevel": {
      "type": "number"
    },
    "notificationSeverities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notifyOnAlarmCreated": {
      "type": "boolean"
    },
    "notifyOnAlarmEscalated": {
      "type": "boolean"
    },
    "notifyOnAlarmCleared": {
      "type": "boolean"
    },
    "canAcknowledgeAlarms": {
      "type": "boolean"
    },
    "hasGlobalAssetAccess": {
      "type": "boolean"
    },
    "hasGlobalDeviceAccess": {
      "type": "boolean"
    },
    "assetIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deviceIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Example:

json

{
  "fullName": "John Doe",
  "email": "john@example.com",
  "role": "TENANT_ADMIN",
  "status": "ACTIVE",
  "notificationsEmailEnabled": true,
  "notificationsMessagingEnabled": false,
  "notificationPhone": "+919876543210",
  "notificationEscalationLevel": 1,
  "notificationSeverities": [
    "WARNING",
    "MINOR",
    "MAJOR",
    "CRITICAL"
  ],
  "notifyOnAlarmCreated": true,
  "notifyOnAlarmEscalated": true,
  "notifyOnAlarmCleared": true,
  "canAcknowledgeAlarms": true,
  "hasGlobalAssetAccess": true,
  "hasGlobalDeviceAccess": true,
  "assetIds": [
    "asset-1",
    "asset-2"
  ],
  "deviceIds": [
    "device-1",
    "device-2"
  ]
}

Responses

201

User created successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "userId",
    "fullName",
    "email",
    "role"
  ],
  "properties": {
    "userId": {
      "type": "string"
    },
    "fullName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "role": {
      "type": "string",
      "enum": [
        "TENANT_OWNER",
        "TENANT_ADMIN",
        "TENANT_RW",
        "TENANT_READ_ONLY"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "DISABLED"
      ]
    },
    "isProtected": {
      "type": "boolean"
    },
    "notificationsEmailEnabled": {
      "type": "boolean"
    },
    "notificationsMessagingEnabled": {
      "type": "boolean"
    },
    "notificationPhone": {
      "type": "string"
    },
    "notificationEscalationLevel": {
      "type": "number"
    },
    "notificationSeverities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notifyOnAlarmCreated": {
      "type": "boolean"
    },
    "notifyOnAlarmEscalated": {
      "type": "boolean"
    },
    "notifyOnAlarmCleared": {
      "type": "boolean"
    },
    "canAcknowledgeAlarms": {
      "type": "boolean"
    },
    "hasGlobalAssetAccess": {
      "type": "boolean"
    },
    "hasGlobalDeviceAccess": {
      "type": "boolean"
    },
    "assetCount": {
      "type": "number"
    },
    "deviceCount": {
      "type": "number"
    },
    "assetIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deviceIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}

Example:

json

{
  "userId": "user-123",
  "fullName": "John Doe",
  "email": "john@example.com",
  "role": "TENANT_ADMIN",
  "status": "ACTIVE",
  "isProtected": false,
  "notificationsEmailEnabled": true,
  "notificationsMessagingEnabled": false,
  "notificationPhone": "+919876543210",
  "notificationEscalationLevel": 1,
  "notificationSeverities": [
    "WARNING",
    "MINOR",
    "MAJOR",
    "CRITICAL"
  ],
  "notifyOnAlarmCreated": true,
  "notifyOnAlarmEscalated": true,
  "notifyOnAlarmCleared": true,
  "canAcknowledgeAlarms": true,
  "hasGlobalAssetAccess": true,
  "hasGlobalDeviceAccess": true,
  "assetCount": 3,
  "deviceCount": 5,
  "assetIds": [
    "asset-1",
    "asset-2"
  ],
  "deviceIds": [
    "device-1",
    "device-2"
  ],
  "createdAt": "2026-04-07T10:00:00.000Z",
  "updatedAt": "2026-04-07T10:30:00.000Z"
}

400

Invalid user payload

No response body.

401

Unauthorized

No response body.

Notes / Constraints

Supported request content types: application/json.
Swagger declares security requirements for this operation.

DELETE `/api/users/{userId}`

Summary: Delete user

Operation ID: UsersController_deleteUser

Tags: Users

Security:

bearer

Parameters

Name	In	Required	Type	Description
userId	path	yes	string	User identifier

Responses

200

User deleted successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean"
    }
  }
}

Example:

json

{
  "success": true
}

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

GET `/api/users/{userId}`

Summary: Get user details

Operation ID: UsersController_getUser

Tags: Users

Security:

bearer

Parameters

Name	In	Required	Type	Description
userId	path	yes	string	User identifier

Responses

200

User returned successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "userId",
    "fullName",
    "email",
    "role"
  ],
  "properties": {
    "userId": {
      "type": "string"
    },
    "fullName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "role": {
      "type": "string",
      "enum": [
        "TENANT_OWNER",
        "TENANT_ADMIN",
        "TENANT_RW",
        "TENANT_READ_ONLY"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "DISABLED"
      ]
    },
    "isProtected": {
      "type": "boolean"
    },
    "notificationsEmailEnabled": {
      "type": "boolean"
    },
    "notificationsMessagingEnabled": {
      "type": "boolean"
    },
    "notificationPhone": {
      "type": "string"
    },
    "notificationEscalationLevel": {
      "type": "number"
    },
    "notificationSeverities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notifyOnAlarmCreated": {
      "type": "boolean"
    },
    "notifyOnAlarmEscalated": {
      "type": "boolean"
    },
    "notifyOnAlarmCleared": {
      "type": "boolean"
    },
    "canAcknowledgeAlarms": {
      "type": "boolean"
    },
    "hasGlobalAssetAccess": {
      "type": "boolean"
    },
    "hasGlobalDeviceAccess": {
      "type": "boolean"
    },
    "assetCount": {
      "type": "number"
    },
    "deviceCount": {
      "type": "number"
    },
    "assetIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deviceIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}

Example:

json

{
  "userId": "user-123",
  "fullName": "John Doe",
  "email": "john@example.com",
  "role": "TENANT_ADMIN",
  "status": "ACTIVE",
  "isProtected": false,
  "notificationsEmailEnabled": true,
  "notificationsMessagingEnabled": false,
  "notificationPhone": "+919876543210",
  "notificationEscalationLevel": 1,
  "notificationSeverities": [
    "WARNING",
    "MINOR",
    "MAJOR",
    "CRITICAL"
  ],
  "notifyOnAlarmCreated": true,
  "notifyOnAlarmEscalated": true,
  "notifyOnAlarmCleared": true,
  "canAcknowledgeAlarms": true,
  "hasGlobalAssetAccess": true,
  "hasGlobalDeviceAccess": true,
  "assetCount": 3,
  "deviceCount": 5,
  "assetIds": [
    "asset-1",
    "asset-2"
  ],
  "deviceIds": [
    "device-1",
    "device-2"
  ],
  "createdAt": "2026-04-07T10:00:00.000Z",
  "updatedAt": "2026-04-07T10:30:00.000Z"
}

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Swagger declares security requirements for this operation.

PATCH `/api/users/{userId}`

Summary: Update user

Operation ID: UsersController_updateUser

Tags: Users

Security:

bearer

Parameters

Name	In	Required	Type	Description
userId	path	yes	string	User identifier

Request

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "properties": {
    "fullName": {
      "type": "string",
      "description": "Full name of the user"
    },
    "email": {
      "type": "string",
      "description": "User email address"
    },
    "role": {
      "type": "string",
      "description": "User role",
      "enum": [
        "TENANT_OWNER",
        "TENANT_ADMIN",
        "TENANT_RW",
        "TENANT_READ_ONLY"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "DISABLED"
      ]
    },
    "notificationsEmailEnabled": {
      "type": "boolean"
    },
    "notificationsMessagingEnabled": {
      "type": "boolean"
    },
    "notificationPhone": {
      "type": "string"
    },
    "notificationEscalationLevel": {
      "type": "number"
    },
    "notificationSeverities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notifyOnAlarmCreated": {
      "type": "boolean"
    },
    "notifyOnAlarmEscalated": {
      "type": "boolean"
    },
    "notifyOnAlarmCleared": {
      "type": "boolean"
    },
    "canAcknowledgeAlarms": {
      "type": "boolean"
    },
    "hasGlobalAssetAccess": {
      "type": "boolean"
    },
    "hasGlobalDeviceAccess": {
      "type": "boolean"
    },
    "assetIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deviceIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Example:

json

{
  "fullName": "John Doe",
  "email": "john@example.com",
  "role": "TENANT_ADMIN",
  "status": "ACTIVE",
  "notificationsEmailEnabled": true,
  "notificationsMessagingEnabled": false,
  "notificationPhone": "+919876543210",
  "notificationEscalationLevel": 1,
  "notificationSeverities": [
    "WARNING",
    "MINOR",
    "MAJOR",
    "CRITICAL"
  ],
  "notifyOnAlarmCreated": true,
  "notifyOnAlarmEscalated": true,
  "notifyOnAlarmCleared": true,
  "canAcknowledgeAlarms": true,
  "hasGlobalAssetAccess": true,
  "hasGlobalDeviceAccess": true,
  "assetIds": [
    "asset-1",
    "asset-2"
  ],
  "deviceIds": [
    "device-1",
    "device-2"
  ]
}

Responses

200

User updated successfully

Content-Type: application/json

Schema:

json

{
  "type": "object",
  "required": [
    "userId",
    "fullName",
    "email",
    "role"
  ],
  "properties": {
    "userId": {
      "type": "string"
    },
    "fullName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "role": {
      "type": "string",
      "enum": [
        "TENANT_OWNER",
        "TENANT_ADMIN",
        "TENANT_RW",
        "TENANT_READ_ONLY"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "DISABLED"
      ]
    },
    "isProtected": {
      "type": "boolean"
    },
    "notificationsEmailEnabled": {
      "type": "boolean"
    },
    "notificationsMessagingEnabled": {
      "type": "boolean"
    },
    "notificationPhone": {
      "type": "string"
    },
    "notificationEscalationLevel": {
      "type": "number"
    },
    "notificationSeverities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "notifyOnAlarmCreated": {
      "type": "boolean"
    },
    "notifyOnAlarmEscalated": {
      "type": "boolean"
    },
    "notifyOnAlarmCleared": {
      "type": "boolean"
    },
    "canAcknowledgeAlarms": {
      "type": "boolean"
    },
    "hasGlobalAssetAccess": {
      "type": "boolean"
    },
    "hasGlobalDeviceAccess": {
      "type": "boolean"
    },
    "assetCount": {
      "type": "number"
    },
    "deviceCount": {
      "type": "number"
    },
    "assetIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deviceIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}

Example:

json

{
  "userId": "user-123",
  "fullName": "John Doe",
  "email": "john@example.com",
  "role": "TENANT_ADMIN",
  "status": "ACTIVE",
  "isProtected": false,
  "notificationsEmailEnabled": true,
  "notificationsMessagingEnabled": false,
  "notificationPhone": "+919876543210",
  "notificationEscalationLevel": 1,
  "notificationSeverities": [
    "WARNING",
    "MINOR",
    "MAJOR",
    "CRITICAL"
  ],
  "notifyOnAlarmCreated": true,
  "notifyOnAlarmEscalated": true,
  "notifyOnAlarmCleared": true,
  "canAcknowledgeAlarms": true,
  "hasGlobalAssetAccess": true,
  "hasGlobalDeviceAccess": true,
  "assetCount": 3,
  "deviceCount": 5,
  "assetIds": [
    "asset-1",
    "asset-2"
  ],
  "deviceIds": [
    "device-1",
    "device-2"
  ],
  "createdAt": "2026-04-07T10:00:00.000Z",
  "updatedAt": "2026-04-07T10:30:00.000Z"
}

400

Invalid user payload

No response body.

401

Unauthorized

No response body.

Notes / Constraints

This endpoint depends on one or more path parameters.
Supported request content types: application/json.
Swagger declares security requirements for this operation.

Module Notes / Constraints

Generated from OpenAPI version metadata: 1.0.
5 operation(s) in this module declare explicit Swagger security requirements.
HTTP methods present in this module: GET, POST, DELETE, PATCH.
This file is generated from Swagger/OpenAPI and should be regenerated when controller, DTO, or Swagger decorator changes affect the spec.

Users Module ​

Overview ​

Key APIs ​

Frontend Usage Flow ​

GET /api/users ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

POST /api/users ​

Request ​

Responses ​

201 ​

400 ​

401 ​

Notes / Constraints ​

DELETE /api/users/{userId} ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

GET /api/users/{userId} ​

Parameters ​

Responses ​

200 ​

401 ​

Notes / Constraints ​

PATCH /api/users/{userId} ​

Parameters ​

Request ​

Responses ​

200 ​

400 ​

401 ​

Notes / Constraints ​

Module Notes / Constraints ​

Users Module

Overview

Key APIs

Frontend Usage Flow

GET `/api/users`

Responses

200

401

Notes / Constraints

POST `/api/users`

Request

Responses

201

400

401

Notes / Constraints

DELETE `/api/users/{userId}`

Parameters

Responses

200

401

Notes / Constraints

GET `/api/users/{userId}`

Parameters

Responses

200

401

Notes / Constraints

PATCH `/api/users/{userId}`

Parameters

Request

Responses

200

400

401

Notes / Constraints

Module Notes / Constraints