Update an existing role's name, description, and permissions
Updates an existing role identified by roleId. Supports renaming the role, updating its description, and modifying product-level module and feature permissions. [0=Full-control; 1=Read-Write; 2=Read-Only; -1=No Access]
Endpoints
Copy full URL
Request URL
https://{server-hostname}:8383/emsapi/roles
Scope
Admin.UPDATECopied!
Header
Authorization: d92d4xxxxxxxxxxxxx15f52
Request Parameters
- Request Headers
acceptstringMandatoryapplication/updateRole.v1+jsonapplication/updateRole.v1+jsonCopied!
Specifies the expected response format. Set to application/updateRole.v1+json to receive the role update response in JSON format.
content-typestringMandatoryapplication/updateRole.v1+jsonapplication/updateRole.v1+jsonCopied!
Specifies the request payload format. Set to application/updateRole.v1+json to submit the role data in JSON format.
- Request Body
application/json
JSON object
Hide Sub-Attributes
roleIdstringMandatory
Unique identifier of the role to be updated. Required for identifying which role to modify.
roleNamestringOptional
Updated name for the role. Supports alphanumeric characters, spaces, and special characters. Maximum 100 characters.
roleDescriptionstringOptional
Updated description of the role's purpose and access level. Maximum 250 characters.
roleDetailsJSON objectOptional
Product-keyed object mapping each product name to its module and feature permission details to be updated for this role.
Show Sub-Attributes
Product nameJSON objectOptional
Product-specific permission block. Each key is the internal product name (e.g., 'DesktopCentral') containing its module configuration. To get product name Get Product Name
Show Sub-Attributes
displayNamestringOptional
display name of the product (e.g., 'Desktop Central', 'Patch Manager Plus').
modulesJSON arrayOptional
List of module objects defining which modules and features within this product are accessible to the role. Max 500 modules.
Show Sub-Attributes
JSON object
Show Sub-Attributes
displayNamestringOptional
Name of the module (e.g., 'Device Management', 'Patch Management').
valuestringOptional
Internal string identifier for the module used by the system (e.g., 'device_mgmt', 'patch_mgmt').
moduleIdlongOptional
Unique numeric ID of the module within the product.
selectedFeaturesarrayOptional
Array of numeric feature IDs granted to this role for this module. Ignored when '-1' is set to true. Max 1000 feature IDs.
-1booleanMandatory
If true, all features in this module are granted to the role, overriding the selectedFeatures list.
uem_safestringbooleanOptional
Dynamic boolean flag for additional access-level permissions specific to the module (e.g., read, write, fullControl flags).
Sample Request
Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request PUT \
--url https://appdomain/emsapi/roles \
--header 'Authorization: d92d4xxxxxxxxxxxxx15f52' \
--header 'accept: application/updateRole.v1+json' \
--header 'content-type: application/updateRole.v1+json' \
--data '{"roleId":"97913000000566047","roleName":"Security Auditor","roleDetails":{"osd":{"modules":[{"0":true,"1":true,"2":true,"-1":false,"value":"OSD Imaging"},{"0":true,"1":true,"2":true,"-1":false,"value":"OSD Deployment"}]},"desktopCentral":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"moduleId":"97913000000010497","value":"Configurations"},{"0":false,"1":false,"2":false,"-1":true,"value":"Patch Management"},{"0":false,"1":false,"2":false,"-1":true,"value":"Vulnerability Mgmt"},{"0":false,"1":false,"2":false,"-1":true,"value":"Software Deployment"},{"0":false,"1":false,"2":false,"-1":true,"moduleId":"97913000000010506","value":"Inventory"},{"0":false,"1":false,"2":false,"-1":true,"moduleId":"97913000000010509","value":"Tools"},{"0":false,"1":false,"2":false,"-1":true,"value":"RDS"},{"0":false,"1":false,"2":false,"-1":true,"value":"Endpoint Intelligence"},{"0":false,"1":false,"2":false,"-1":true,"value":"Sensors"},{"0":false,"1":false,"2":false,"-1":true,"value":"UEMSWorkflow"},{"0":false,"1":false,"2":false,"-1":true,"value":"Reports"},{"-1":true,"value":"Query Reports"},{"0":true,"1":true,"2":true,"-1":false,"value":"SOM"}]},"mdm":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"MDM Enrollment"}]},"SecurityAddOn":{"modules":[{"0":true,"1":true,"2":true,"-1":false,"value":"Application Control"}]},"browserSecurity":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"BSP Inventory"}]}},"roleDescription":"Security Auditor"}'▼ Show full
Sample Request Body
Update role with full module structure across desktopCentral, osd, browserSecurity, SecurityAddOn, and mdm.
Copied!
{
"roleId": "97913000000566047",
"roleName": "Security Auditor",
"roleDetails": {
"osd": {
"modules": [
{
"0": true,
"1": true,
"2": true,
"-1": false,
"value": "OSD Imaging"
},
{
"0": true,
"1": true,
"2": true,
"-1": false,
"value": "OSD Deployment"
}
]
},
"desktopCentral": {
"modules": [
{
"0": false,
"1": false,
"2": false,
"-1": true,
"moduleId": "97913000000010497",
"value": "Configurations"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "Patch Management"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "Vulnerability Mgmt"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "Software Deployment"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"moduleId": "97913000000010506",
"value": "Inventory"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"moduleId": "97913000000010509",
"value": "Tools"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "RDS"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "Endpoint Intelligence"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "Sensors"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "UEMSWorkflow"
},
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "Reports"
},
{
"-1": true,
"value": "Query Reports"
},
{
"0": true,
"1": true,
"2": true,
"-1": false,
"value": "SOM"
}
]
},
"mdm": {
"modules": [
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "MDM Enrollment"
}
]
},
"SecurityAddOn": {
"modules": [
{
"0": true,
"1": true,
"2": true,
"-1": false,
"value": "Application Control"
}
]
},
"browserSecurity": {
"modules": [
{
"0": false,
"1": false,
"2": false,
"-1": true,
"value": "BSP Inventory"
}
]
}
},
"roleDescription": "Security Auditor"
}
▼ Show full
Response Parameters
- HTTP code 200
Response Body - application/json
JSON object
Hide Sub-Attributes
roleIdstring
Unique identifier of the updated role.
roleNamestring
Name of the role after the update.
messagestring
Success message confirming role update.
successCodestring
Success code for the role update operation.
- HTTP code 412
Response Body - application/json
JSON object
Hide Sub-Attributes
errorCodestring
Application-specific error code indicating the reason for the request failure.
errorMsgstring
Error message describing the cause of the error.
Possible Response Codes
200HTTP code
412HTTP code
Sample Response: HTTP 200
Role update success response.
Copied!
{
"roleId": "97913000000010554",
"roleName": "Endpoint Technician",
"message": "Role Endpoint Technician has been modified successfully.",
"successCode": "40019"
}
▼ Show full
Sample Response: HTTP 412
The Role Name already exists. Please choose a different name.
Copied!
{
"errorCode": "40018",
"errorMsg": "Role name Product Admin already exists."
}
▼ Show full
Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes
Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.