# **AIRBNB**

**FRONTEND GUIDE FOR AI CODING AGENTS - PART 5 - User Management**

This document is the 2nd part of a REST API guide for the airbnb project.
It is designed for AI agents that will generate frontend code to consume the project's backend.

This document provides extensive instruction for administrative user management.

## Service Access

User management is handled through auth service again.

Auth service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs.
The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the auth service, the base URLs are:

* **Preview:** `https://airbnb3.prw.mindbricks.com/auth-api`
* **Staging:** `https://airbnb3-stage.mindbricks.co/auth-api`
* **Production:** `https://airbnb3.mindbricks.co/auth-api`

Please note that any feature in this document is open to admins only. When the user logins, the response includes a roleId field.

This roleId should one of these following admin roles. `superAdmin`, `admin`, 

## Scope

Auth service provides following feature for user management in airbnb application.

These features are already handled in the previous part.
1. User Registration
2. User Authentication
3. Password Reset
3. Email (and/or) Mobile Verification
4. Profile Management

These features will be handled in this part.
- User Management
- User Groups Management
- Permission Manageemnt

## API Structure

### Object Structure of a Successful Response

When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client.

**HTTP Status Codes:**

* **200 OK**: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
* **201 Created**: Returned for CREATE operations, indicating that the resource was created successfully.

**Success Response Format:**

For successful operations, the response includes a `"status": "OK"` property, signaling that the request executed successfully. The structure of a successful response is outlined below:

```json
{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}
```

* **`products`**: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

### Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API's response signature.

### Error Response

If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity:

* **400 Bad Request**: The request was improperly formatted or contained invalid parameters.
* **401 Unauthorized**: The request lacked a valid authentication token; login is required.
* **403 Forbidden**: The current token does not grant access to the requested resource.
* **404 Not Found**: The requested resource was not found on the server.
* **500 Internal Server Error**: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

```js
{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}
```

## User Management

User management will be one of the main parts of the administrative manageemnts, so there will be a minimal but fancy `users` page in the admin dashboard.

### User Roles

- `superadmin` : The first creator of the backend, the owner of the application, root user, has got an absolute authroization on all actions. It can not be assgined any other user. It can't be unassigned. Super admin user can not be deleted in any way.
- `admin` : The role that can be assigned to any user by the super admin. This role includes most permissions that super admin have, but admins can't assign admin roles, can't unassign an admin role, can't delete other users who have admin role. In addition to these limitations, some critical actions in the business services may also be open to only super admin.
- `user` : The standard role that is assgined to every user when first created or registered. This role doesnt have any privilages and can access to their own data or public data. 

    

The roles object is a hardcoded object in the generated code, and it contains the following roles:
```json
{
  "superAdmin": "'superAdmin'",
  "admin": "'admin'",
  "user": "'user'"
}
```

Each user may have only one role, and it is given in `/login` , `/currentuser` or `/users/:userId`  response as follows

```json
{
  // ...
  "roleId":"superAdmin",
  // ...
}
```
  

## Listing Users

You can list users using the `listUsers` api. 

### `List Users` API
The list of users is filtered by the tenantId.


**Rest Route**

The `listUsers` API REST controller can be triggered via the following route:

`/v1/users`


**Rest Request Parameters**



**Filter Parameters**

The `listUsers` api supports 3 optional filter parameters for filtering list results:

**email** (`String`):  A string value to represent the user's email.

- Single (partial match, case-insensitive): `?email=<value>`
- Multiple: `?email=<value1>&email=<value2>`
- Null: `?email=null`


**fullname** (`String`): A string value to represent the fullname of the user

- Single (partial match, case-insensitive): `?fullname=<value>`
- Multiple: `?fullname=<value1>&fullname=<value2>`
- Null: `?fullname=null`


**roleId** (`String`): A string value to represent the roleId of the user.

- Single (partial match, case-insensitive): `?roleId=<value>`
- Multiple: `?roleId=<value1>&roleId=<value2>`
- Null: `?roleId=null`



**REST Request**
To access the api you can use the **REST** controller with the path **GET  /v1/users**
```js
  axios({
    method: 'GET',
    url: '/v1/users',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // email: '<value>' // Filter by email
        // fullname: '<value>' // Filter by fullname
        // roleId: '<value>' // Filter by roleId
            }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "users",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"users": [
		{
			"id": "ID",
			"email": "String",
			"password": "String",
			"fullname": "String",
			"avatar": "String",
			"roleId": "String",
			"emailVerified": "Boolean",
			"preferredLanguage": "String",
			"bio": "Text",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}
```


## Searching Users
You may search users with their full names, emails. The search is done in elasticsearch index of the user table so a fast response is provided by the backend. You can send search request on each character update in the search box but start searching after 3 chars.
The keyword parameter that is used in the business logic of the api, is read from the keyword query parameter.

eg: `GET /v1/searchusers?keyword=Joe`

When the user deletes the search keyword, use the `listUsers` api to get the full list again.

### `Search Users` API
The list of users is filtered by the tenantId.


**Rest Route**

The `searchUsers` API REST controller can be triggered via the following route:

`/v1/searchusers`


**Rest Request Parameters**


The `searchUsers` api has got 1 regular request parameter  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| keyword  | String  | true | request.query?.["keyword"] |
**keyword** : 


**Filter Parameters**

The `searchUsers` api supports 1 optional filter parameter for filtering list results:

**roleId** (`String`): A string value to represent the roleId of the user.

- Single (partial match, case-insensitive): `?roleId=<value>`
- Multiple: `?roleId=<value1>&roleId=<value2>`
- Null: `?roleId=null`



**REST Request**
To access the api you can use the **REST** controller with the path **GET  /v1/searchusers**
```js
  axios({
    method: 'GET',
    url: '/v1/searchusers',
    data: {
    
    },
    params: {
             keyword:'"String"',  
    
        // Filter parameters (see Filter Parameters section above)
        // roleId: '<value>' // Filter by roleId
            }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "users",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"users": [
		{
			"id": "ID",
			"email": "String",
			"password": "String",
			"fullname": "String",
			"avatar": "String",
			"roleId": "String",
			"emailVerified": "Boolean",
			"preferredLanguage": "String",
			"bio": "Text",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}
```


#### Pagination
When you list the users please use pagination. To be able to use pagination you should provide a `pageNumber` paramater in the query. The default row count for one page is 25, add an option for user to change it to 50 or 100. You can provide this value to the api through the `pageRowCount` parameter;

`GET /users?pageNumber=1&pageRowCount=50`

## Creating Users

The user management console in the admin dashboard should provide UX components for user creating by admins. When creating users, it should also be possible to upload user avatar. Note that when creating, updating users, admins can not set emailVerified as true, since it is a logical mechanism and should be verified only through verification processes.

### `Create User` API
This api is used by admin roles to create a new user manually from admin panels


**Rest Route**

The `createUser` API REST controller can be triggered via the following route:

`/v1/users`


**Rest Request Parameters**


The `createUser` api has got 6 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| avatar  | String  | false | request.body?.["avatar"] |
| email  | String  | true | request.body?.["email"] |
| password  | String  | true | request.body?.["password"] |
| fullname  | String  | true | request.body?.["fullname"] |
| preferredLanguage  | String  | false | request.body?.["preferredLanguage"] |
| bio  | Text  | false | request.body?.["bio"] |
**avatar** : The avatar url of the user. If not sent, a default random one will be generated.
**email** :  A string value to represent the user's email.
**password** :  A string value to represent the user's password. It will be stored as hashed.
**fullname** : A string value to represent the fullname of the user
**preferredLanguage** : User's preferred language for the application interface
**bio** : User's biography or profile description



**REST Request**
To access the api you can use the **REST** controller with the path **POST  /v1/users**
```js
  axios({
    method: 'POST',
    url: '/v1/users',
    data: {
            avatar:"String",  
            email:"String",  
            password:"String",  
            fullname:"String",  
            preferredLanguage:"String",  
            bio:"Text",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```


### Avatar Upload

Avatars are stored in the auth service's **database bucket** — no external bucket service needed. Upload the avatar image to the auth service's userAvatars bucket endpoint:

`POST {authBaseUrl}/bucket/userAvatars/upload`

Use the regular access token (Bearer header) for authentication — the same token used for all other API calls. The upload body is `multipart/form-data` with a `file` field.

After upload, the response returns file metadata including `id` and `accessKey`. Construct a public download URL and save it in the user's `avatar` field:

```js
const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/key/${result.file.accessKey}`;
await updateUser(userId, { avatar: avatarUrl });
```

Since the userAvatars bucket has public read access, avatar URLs work directly in `<img>` tags without auth.

Before the avatar upload, use the `react-easy-crop` lib for zoom, pan and crop. This component is also used in the profile page — reuse the existing code.

## Updating Users

User update is possible by `updateUser`api. However since this update api is also called by teh user themselves it is lmited with name and avatar change (or any other user related property). 
For roleId and password updates seperate apis are used. So arrange the user update UI as to update the user info, as to set roleId and as to update password. 

### `Update User` API
This route is used by admins to update user profiles.


**Rest Route**

The `updateUser` API REST controller can be triggered via the following route:

`/v1/users/:userId`


**Rest Request Parameters**


The `updateUser` api has got 5 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userId  | ID  | true | request.params?.["userId"] |
| fullname  | String  | false | request.body?.["fullname"] |
| avatar  | String  | false | request.body?.["avatar"] |
| preferredLanguage  | String  | false | request.body?.["preferredLanguage"] |
| bio  | Text  | false | request.body?.["bio"] |
**userId** : This id paremeter is used to select the required data object that will be updated
**fullname** : A string value to represent the fullname of the user
**avatar** : The avatar url of the user. A random avatar will be generated if not provided
**preferredLanguage** : User's preferred language for the application interface
**bio** : User's biography or profile description



**REST Request**
To access the api you can use the **REST** controller with the path **PATCH  /v1/users/:userId**
```js
  axios({
    method: 'PATCH',
    url: `/v1/users/${userId}`,
    data: {
            fullname:"String",  
            avatar:"String",  
            preferredLanguage:"String",  
            bio:"Text",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```


For role updates there are some rules.
1. Superadmin role can not be unassigned even by superadmin.
2. Admin roles can be assgined or unassgined only by superadmin.
3. All other roles can be assigned and unassgined by admins and superadmin.

For password updates there are some rules.
1. Superadmin and admin passwords can be updated only by superadmin. 
2. Admins can update only non-admin passwords.

### `Update Userrole` API
This route is used by admin roles to update the user role.The default role is user when a user is registered. A user's role can be updated by superAdmin or admin


**Rest Route**

The `updateUserRole` API REST controller can be triggered via the following route:

`/v1/userrole/:userId`


**Rest Request Parameters**


The `updateUserRole` api has got 2 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userId  | ID  | true | request.params?.["userId"] |
| roleId  | String  | true | request.body?.["roleId"] |
**userId** : This id paremeter is used to select the required data object that will be updated
**roleId** : The new roleId of the user to be updated



**REST Request**
To access the api you can use the **REST** controller with the path **PATCH  /v1/userrole/:userId**
```js
  axios({
    method: 'PATCH',
    url: `/v1/userrole/${userId}`,
    data: {
            roleId:"String",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```


### `Update Userpasswordbyadmin` API
This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords


**Rest Route**

The `updateUserPasswordByAdmin` API REST controller can be triggered via the following route:

`/v1/userpasswordbyadmin/:userId`


**Rest Request Parameters**


The `updateUserPasswordByAdmin` api has got 2 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userId  | ID  | true | request.params?.["userId"] |
| password  | String  | true | request.body?.["password"] |
**userId** : This id paremeter is used to select the required data object that will be updated
**password** : The new password of the user to be updated



**REST Request**
To access the api you can use the **REST** controller with the path **PATCH  /v1/userpasswordbyadmin/:userId**
```js
  axios({
    method: 'PATCH',
    url: `/v1/userpasswordbyadmin/${userId}`,
    data: {
            password:"String",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```


### Deleting Users

Deleting users is possible in certain conditions.

1. SuperAdmin can not be deleted.
2. Admins can be deleted by only superadmin.
3. Users can be deleted by admins or superadmin.

### `Delete User` API
This api is used by admins to delete user profiles.


**Rest Route**

The `deleteUser` API REST controller can be triggered via the following route:

`/v1/users/:userId`


**Rest Request Parameters**


The `deleteUser` api has got 1 regular request parameter  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userId  | ID  | true | request.params?.["userId"] |
**userId** : This id paremeter is used to select the required data object that will be deleted



**REST Request**
To access the api you can use the **REST** controller with the path **DELETE  /v1/users/:userId**
```js
  axios({
    method: 'DELETE',
    url: `/v1/users/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```


---


## User Group Management

This application backend provides user groups with two data tables, UserGroup and UserGroupMember, so the admin dashboard UI should support user group creating/deleting and adding or removing member users to the groups.

Design a minimal and fancy user group management console where we can manage the groups and their members. The user groups may be in a main list and when selected a right drawer can show the members of the group, and at the bottom of the drawer there can be a user search area to select the user to be added to the group. For user searching use the user search api and make a call to the api in each character added to the search edit box. 

To manage user groups and members, use the related apis below.

### `Create Usergroup` API
This route is used by admin roles to create a new usergroup manually from admin panels


**Rest Route**

The `createUserGroup` API REST controller can be triggered via the following route:

`/v1/usergroups`


**Rest Request Parameters**


The `createUserGroup` api has got 2 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| avatar  | String  | false | request.body?.["avatar"] |
| groupName  | String  | true | request.body?.["groupName"] |
**avatar** : A string value to represent the groups icon.
**groupName** :  A string value to represent the group name.



**REST Request**
To access the api you can use the **REST** controller with the path **POST  /v1/usergroups**
```js
  axios({
    method: 'POST',
    url: '/v1/usergroups',
    data: {
            avatar:"String",  
            groupName:"String",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```

### `Update Usergroup` API
This route is used by admin to update user groups.


**Rest Route**

The `updateUserGroup` API REST controller can be triggered via the following route:

`/v1/usergroups/:userGroupId`


**Rest Request Parameters**


The `updateUserGroup` api has got 3 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userGroupId  | ID  | true | request.params?.["userGroupId"] |
| groupName  | String  | false | request.body?.["groupName"] |
| avatar  | String  | false | request.body?.["avatar"] |
**userGroupId** : This id paremeter is used to select the required data object that will be updated
**groupName** :  A string value to represent the group name.
**avatar** :  A string value to represent the groups icon.



**REST Request**
To access the api you can use the **REST** controller with the path **PATCH  /v1/usergroups/:userGroupId**
```js
  axios({
    method: 'PATCH',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
            groupName:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```

### `Delete Usergroup` API
This route is used by admin to delete a user group.


**Rest Route**

The `deleteUserGroup` API REST controller can be triggered via the following route:

`/v1/usergroups/:userGroupId`


**Rest Request Parameters**


The `deleteUserGroup` api has got 1 regular request parameter  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userGroupId  | ID  | true | request.params?.["userGroupId"] |
**userGroupId** : This id paremeter is used to select the required data object that will be deleted



**REST Request**
To access the api you can use the **REST** controller with the path **DELETE  /v1/usergroups/:userGroupId**
```js
  axios({
    method: 'DELETE',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```

### `Get Usergroup` API
This is a public route to get the user group information.


**Rest Route**

The `getUserGroup` API REST controller can be triggered via the following route:

`/v1/usergroups/:userGroupId`


**Rest Request Parameters**


The `getUserGroup` api has got 1 regular request parameter  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userGroupId  | ID  | true | request.params?.["userGroupId"] |
**userGroupId** : This id paremeter is used to query the required data object.



**REST Request**
To access the api you can use the **REST** controller with the path **GET  /v1/usergroups/:userGroupId**
```js
  axios({
    method: 'GET',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```

### `List Usergroups` API
This is a public route to get the list of groups.


**Rest Route**

The `listUserGroups` API REST controller can be triggered via the following route:

`/v1/usergroups`


**Rest Request Parameters**



**Filter Parameters**

The `listUserGroups` api supports 2 optional filter parameters for filtering list results:

**groupName** (`String`):  A string value to represent the group name.

- Single (partial match, case-insensitive): `?groupName=<value>`
- Multiple: `?groupName=<value1>&groupName=<value2>`
- Null: `?groupName=null`


**avatar** (`String`):  A string value to represent the groups icon.

- Single (partial match, case-insensitive): `?avatar=<value>`
- Multiple: `?avatar=<value1>&avatar=<value2>`
- Null: `?avatar=null`



**REST Request**
To access the api you can use the **REST** controller with the path **GET  /v1/usergroups**
```js
  axios({
    method: 'GET',
    url: '/v1/usergroups',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // groupName: '<value>' // Filter by groupName
        // avatar: '<value>' // Filter by avatar
            }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroups",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userGroups": [
		{
			"id": "ID",
			"groupName": "String",
			"avatar": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}
```


A user group member is stored in the db with `groupId` and `userId` fields. The `id` field identifies the membership, so when removing a user from a group, the membership record (UserGroupMember) should be deleted by this id. The UserGroupMember record also has an ownerId which is automatically added to teh record from the session's userId. This ownerId identifes the admin user who added the user to the group.

### `Create Usergroupmember` API
This route is used by admin roles to add a user to a group.


**Rest Route**

The `createUserGroupMember` API REST controller can be triggered via the following route:

`/v1/usergroupmembers`


**Rest Request Parameters**


The `createUserGroupMember` api has got 2 regular request parameters  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| groupId  | ID  | true | request.body?.["groupId"] |
| userId  | ID  | true | request.body?.["userId"] |
**groupId** :  An ID value to represent the group that the user is asssigned as a memeber to.
**userId** :  An ID value to represent the user that is assgined as a member to the group.



**REST Request**
To access the api you can use the **REST** controller with the path **POST  /v1/usergroupmembers**
```js
  axios({
    method: 'POST',
    url: '/v1/usergroupmembers',
    data: {
            groupId:"ID",  
            userId:"ID",  
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```

### `Delete Usergroupmember` API
This route is used by admin to delete a member from a group.


**Rest Route**

The `deleteUserGroupMember` API REST controller can be triggered via the following route:

`/v1/usergroupmembers/:userGroupMemberId`


**Rest Request Parameters**


The `deleteUserGroupMember` api has got 1 regular request parameter  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| userGroupMemberId  | ID  | true | request.params?.["userGroupMemberId"] |
**userGroupMemberId** : This id paremeter is used to select the required data object that will be deleted



**REST Request**
To access the api you can use the **REST** controller with the path **DELETE  /v1/usergroupmembers/:userGroupMemberId**
```js
  axios({
    method: 'DELETE',
    url: `/v1/usergroupmembers/${userGroupMemberId}`,
    data: {
    
    },
    params: {
    
        }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}
```

### `List Usergroupmembers` API
This is a public route to get the list of group members of a group.


**Rest Route**

The `listUserGroupMembers` API REST controller can be triggered via the following route:

`/v1/listusergroupmembers/:groupId`


**Rest Request Parameters**


The `listUserGroupMembers` api has got 1 regular request parameter  

| Parameter              | Type                   | Required | Population                   |
| ---------------------- | ---------------------- | -------- | ---------------------------- |
| groupId  | ID  | true | request.params?.["groupId"] |
**groupId** :  An ID value to represent the group that the user is asssigned as a memeber to.. The parameter is used to query data.


**Filter Parameters**

The `listUserGroupMembers` api supports 2 optional filter parameters for filtering list results:

**userId** (`ID`):  An ID value to represent the user that is assgined as a member to the group.

- Single: `?userId=<value>`
- Multiple: `?userId=<value1>&userId=<value2>`
- Null: `?userId=null`


**ownerId** (`ID`): An ID value to represent the admin user who assgined the member.

- Single: `?ownerId=<value>`
- Multiple: `?ownerId=<value1>&ownerId=<value2>`
- Null: `?ownerId=null`



**REST Request**
To access the api you can use the **REST** controller with the path **GET  /v1/listusergroupmembers/:groupId**
```js
  axios({
    method: 'GET',
    url: `/v1/listusergroupmembers/${groupId}`,
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // ownerId: '<value>' // Filter by ownerId
            }
  });
```   
**REST Response**


```json
{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMembers",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userGroupMembers": [
		{
			"id": "ID",
			"groupId": "ID",
			"userId": "ID",
			"ownerId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}
```


When you list user group members, a `user` object will also be inserted in each userGroupMember object, with fullname, avatar, email.

## Avatar Storage (Database Buckets)

(This information is also covered in the Profile prompt.)

Avatars are stored in the auth service's **database buckets** — uploaded to and downloaded from the auth service directly using the regular access token.

**User Avatar Bucket:**
- Upload: `POST {authBaseUrl}/bucket/userAvatars/upload` (multipart/form-data, `file` field)
- Download: `GET {authBaseUrl}/bucket/userAvatars/download/key/{accessKey}` (public, no auth needed)
- Allowed: image/png, image/jpeg, image/webp, image/gif (max 5 MB)



When uploading an avatar (for user creation or update), send the image to the bucket, get back the `accessKey`, construct the download URL, and store it in the user's `avatar` field via the update API.

**After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.**