Fetch module and permission template for role creation

Retrieves the role template payload used when creating roles, including product modules and permission flags. [0=Full-control; 1=Read-Write; 2=Read-Only; -1=No Access]

Endpoints

get /emsapi/roles

Copy full URL

Request URL

https://{serverurl}/emsapi/roles

Scope

DesktopCentralCloud.Admin.READCopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

acceptstringMandatory

application/umRoles.v1+jsonCopied!

Specifies the expected response format. Set to application/addRole.v1+json to receive the role creation response template in JSON format.

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request GET \
  --url https://appdomains/emsapi/roles \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'accept: application/umRoles.v1+json'

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("accept", "application/umRoles.v1+json")
        .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 = {
    'accept': "application/umRoles.v1+json",
    'Authorization': "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52"
    }

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

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

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


    headersMap = Map();
    headersMap.put("accept", "application/umRoles.v1+json");

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

    info response;

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

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Hide Sub-Attributes

roleDetailsJSON Object

Product-keyed permission template used while creating a role. Each product contains module list and access flags.

Show Sub-Attributes

uem_safestringJSON Object

Product-specific permission template. Each key is the internal product name (e.g., 'desktopCentral', 'osd', 'mdm', 'SecurityAddOn') containing its module configuration template.

Show Sub-Attributes

displayNamestring

Display name of the product (e.g., 'Endpoint Control', 'OSD Control', 'MDM', 'Security Add-on Control').

modulesJSON Array

List of module permission template objects showing which modules are available for this product. Each module includes default permission flags and optional feature restrictions.

Show Sub-Attributes

JSON Object

Show Sub-Attributes

0boolean

Default permission flag for access level 0.

1boolean

Default permission flag for access level 1.

2boolean

Default permission flag for access level 2.

displayNamestring

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

valuestring

Internal value identifier for the module used when creating or updating roles (e.g., 'Configurations', 'Patch Management', 'MDM Enrollment').

isFeatureRestrictionAllowedJSON Object

Access-level restriction details for modules that support 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

Full module access flag. When true, grants complete access to the module.

Possible Response Codes

200HTTP code

Sample Response: HTTP 200

Role creation template payload with product modules and default permission flags.

Copied!

  {
    "roleDetails": {
      "osd": {
        "displayName": "OSD Control",
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Imaging",
            "value": "OSD Imaging"
          },
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Deployment",
            "value": "OSD Deployment"
          }
        ]
      },
      "desktopCentral": {
        "displayName": "Endpoint Control",
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "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"
          },
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Inventory",
            "isFeatureRestrictionAllowed": {
              "read": 0,
              "fullControl": 0,
              "write": 0
            },
            "moduleId": "97913000000010506",
            "value": "Inventory"
          }
        ]
      },
      "mdm": {
        "displayName": "MDM",
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Enrollment",
            "value": "MDM Enrollment"
          },
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Inventory",
            "isFeatureRestrictionAllowed": {
              "read": 0,
              "fullControl": 0,
              "write": 0
            },
            "moduleId": "186245000000000405",
            "value": "MDM Inventory"
          }
        ]
      },
      "SecurityAddOn": {
        "displayName": "Security Add-on Control",
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Application Control",
            "value": "Application Control"
          },
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "displayName": "Next-Gen Antivirus",
            "value": "NGAV Mgmt"
          }
        ]
      }
    }
  }

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