Retrieve a specific role and its permissions by roleId

Retrieves the full details of a specific role identified by its roleId, including its description and the complete product-level module and feature permission map.

Endpoints

get /emsapi/roles/{roleId}

Copy full URL

Request URL

https://{serverurl}/emsapi/roles/{roleId}

Scope

DesktopCentralCloud.Admin.READCopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Path Parameters

roleIdstringMandatory

Unique role identifier. To get role id click here. Get Role Id

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request GET \
  --url https://appdomains/emsapi/roles/{roleId} \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52'

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/{roleId}"))
        .header("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

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

headers = { 'Authorization': "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52" }

conn.request("GET", "/emsapi/roles/{roleId}", headers=headers)

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

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


    headersMap = Map();
    headersMap.put("Accept", "application/json");

    response = invokeUrl
    [
        url: "https://appDomains/emsapi/roles/{roleId}"
        type: GET
        headers: headersMap
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomains/emsapi/roles/{roleId}' -Method GET -Headers $headers

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Hide Sub-Attributes

roleIdstring

Unique role identifier.

roleNamestring

Name of the role as configured in the system.

roleDescriptionstring

Description of the role's purpose and access level.

roleDetailsJSON Object

Product-keyed map of module and feature permissions assigned to this role. Each key represents a product name.

Show Sub-Attributes

uem_safestringJSON Object

Product-specific permission block. Each key is the internal product name (e.g., 'DesktopCentral') containing its module configuration.

Show Sub-Attributes

displayNamestring

Display name of the product (e.g., 'Desktop Central', 'Patch Manager Plus').

modulesJSON Array

List of module permission objects showing which modules and features are accessible under this product for the role.

Show Sub-Attributes

JSON Object

Show Sub-Attributes

0boolean

Permission flag for access level 0.

1boolean

Permission flag for access level 1.

2boolean

Permission flag for access level 2.

displayNamestring

Module name (e.g., 'Configurations', 'Patch Management', 'Inventory').

valuestring

Internal value identifier for the module as returned by the API.

isFeatureRestrictionAllowedJSON Object

Access-level restriction details for modules supporting read/write/fullControl granularity.

Show Sub-Attributes

readinteger

Read access level for the module.

writeinteger

Write access level for the module.

fullControlinteger

Full control access level for the module.

moduleIdstring

Module identifier. The Module ID can be fetched using the following API Get Module ID

-1boolean

Indicates full module access when set to true.

Possible Response Codes

200HTTP code

Sample Response: HTTP 200

Shortened response example for get role by ID, showing product-level modules, optional feature restriction object, and 0/1/2/-1 boolean flags.

Copied!

  {
    "roleId": "97913000000010560",
    "roleName": "Security Auditor",
    "roleDetails": {
      "desktopCentral": {
        "displayName": "Endpoint Control",
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": false,
            "displayName": "Configurations",
            "isFeatureRestrictionAllowed": {
              "read": 2,
              "fullControl": 0,
              "write": 0
            },
            "moduleId": "97913000000010497",
            "value": "Configurations"
          },
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Patch Management",
            "value": "Patch Management"
          }
        ]
      },
      "mdm": {
        "displayName": "MDM",
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Inventory",
            "isFeatureRestrictionAllowed": {
              "fullControl": 0,
              "read": 0,
              "write": 0
            },
            "moduleId": "186245000000000405",
            "value": "MDM Inventory"
          },
          {
            "0": true,
            "1": false,
            "2": false,
            "-1": false,
            "displayName": "Report",
            "value": "MDM Report"
          }
        ]
      }
    },
    "roleDescription": "Read-only access to compliance dashboards, reports, and audit insights."
  }

▼ 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.