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

put /emsapi/roles

Copy full URL

Request URL

https://{serverurl}/emsapi/roles

Scope

DesktopCentralCloud.Admin.UPDATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

acceptstringMandatory

application/updateRole.v1+jsonCopied!

Specifies the expected response format. Set to application/updateRole.v1+json to receive the role update response in JSON format.

content-typestringMandatory

application/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://appdomains/emsapi/roles \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'accept: application/updateRole.v1+json' \
  --header 'content-type: application/updateRole.v1+json' \
  --data '{"roleId":"97913000000566047"}'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://appdomains/emsapi/roles"))
        .header("content-type", "application/updateRole.v1+json")
        .header("accept", "application/updateRole.v1+json")
        .header("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
        .method("PUT", HttpRequest.BodyPublishers.ofString("{\"roleId\":\"97913000000566047\"}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("appdomains")

payload = "{\"roleId\":\"97913000000566047\"}"

headers = {
    'content-type': "application/updateRole.v1+json",
    'accept': "application/updateRole.v1+json",
    'Authorization': "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52"
    }

conn.request("PUT", "/emsapi/roles", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("accept", "application/updateRole.v1+json");
    headersMap.put("content-type", "application/updateRole.v1+json");

    data=Map();
    data.put("roleId","value");

    response = invokeUrl
    [
        url: "https://appDomains/emsapi/roles"
        type: PUT
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("content-type", "application/updateRole.v1+json")
$headers.Add("accept", "application/updateRole.v1+json")
$headers.Add("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomains/emsapi/roles' -Method PUT -Headers $headers -ContentType 'application/updateRole.v1+json' -Body '{"roleId":"97913000000566047"}'

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.