Create a new role

Creates a new role with the specified name, description, and product-level module permissions. [0=Full-control; 1=Read-Write; 2=Read-Only; -1=No Access]

Endpoints

post /emsapi/roles

Copy full URL

Request URL

https://{server-hostname}:8383/emsapi/roles

Scope

Admin.CREATECopied!

Header

Authorization: d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

acceptstringMandatory

application/addRole.v1+jsonCopied!

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

content-typestringMandatory

application/addRole.v1+jsonCopied!

Specifies the request payload format. Set to application/addRole.v1+json to submit the role data in JSON format.

- Request Body

application/json

JSON object

Hide Sub-Attributes

roleNamestringMandatory

Unique name for the new role. Supports alphanumeric characters, spaces, and special characters. Maximum 100 characters.

roleDescriptionstringMandatory

Optional description of the role's purpose and access level. Maximum 250 characters.

roleDetailsJSON objectMandatory

Product-keyed object mapping each product name to its module and feature permission details 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 POST \
  --url https://appdomain/emsapi/roles \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'accept: application/addRole.v1+json' \
  --header 'content-type: application/addRole.v1+json' \
  --data '{"roleName":"testrole","roleDetails":{"osd":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"OSD Imaging"}]},"desktopCentral":{"modules":[{"0":true,"1":true,"2":true,"-1":false,"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"}]},"mdm":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"MDM Enrollment"}]}},"roleDescription":"sadasd"}'

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://appdomain/emsapi/roles"))
        .header("content-type", "application/addRole.v1+json")
        .header("accept", "application/addRole.v1+json")
        .header("Authorization", " d92d4xxxxxxxxxxxxx15f52")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"roleName\":\"testrole\",\"roleDetails\":{\"osd\":{\"modules\":[{\"0\":false,\"1\":false,\"2\":false,\"-1\":true,\"value\":\"OSD Imaging\"}]},\"desktopCentral\":{\"modules\":[{\"0\":true,\"1\":true,\"2\":true,\"-1\":false,\"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\"}]},\"mdm\":{\"modules\":[{\"0\":false,\"1\":false,\"2\":false,\"-1\":true,\"value\":\"MDM Enrollment\"}]}},\"roleDescription\":\"sadasd\"}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

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

payload = "{\"roleName\":\"testrole\",\"roleDetails\":{\"osd\":{\"modules\":[{\"0\":false,\"1\":false,\"2\":false,\"-1\":true,\"value\":\"OSD Imaging\"}]},\"desktopCentral\":{\"modules\":[{\"0\":true,\"1\":true,\"2\":true,\"-1\":false,\"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\"}]},\"mdm\":{\"modules\":[{\"0\":false,\"1\":false,\"2\":false,\"-1\":true,\"value\":\"MDM Enrollment\"}]}},\"roleDescription\":\"sadasd\"}"

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

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

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

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


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

    data=Map();
    data.put("roleName","value");
    data.put("roleDescription","value");
    data_roleDetails=Map();
    data_roleDetails_Product_name=Map();
    data_roleDetails_Product_name.put("displayName","value");
    data_roleDetails_Product_name_modules=List();
    data_roleDetails_Product_name_modules_item1=Map();
    data_roleDetails_Product_name_modules_item1.put("displayName","value");
    data_roleDetails_Product_name_modules_item1.put("value","value");
    data_roleDetails_Product_name_modules_item1.put("moduleId","1");
    data_roleDetails_Product_name_modules_item1_selectedFeatures=List();
    data_roleDetails_Product_name_modules_item1_selectedFeatures.add("1");
    data_roleDetails_Product_name_modules_item1.put("selectedFeatures",data_roleDetails_Product_name_modules_item1_selectedFeatures);
    data_roleDetails_Product_name_modules_item1.put("-1",true);
    data_roleDetails_Product_name_modules_item1.put("uem_safestring",true);
    data_roleDetails_Product_name_modules.add(data_roleDetails_Product_name_modules_item1);
    data_roleDetails_Product_name.put("modules",data_roleDetails_Product_name_modules);
    data_roleDetails.put("Product name",data_roleDetails_Product_name);
    data.put("roleDetails",data_roleDetails);

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

    info response;

$headers=@{}
$headers.Add("content-type", "application/addRole.v1+json")
$headers.Add("accept", "application/addRole.v1+json")
$headers.Add("Authorization", " d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomain/emsapi/roles' -Method POST -Headers $headers -ContentType 'application/addRole.v1+json' -Body '{"roleName":"testrole","roleDetails":{"osd":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"OSD Imaging"}]},"desktopCentral":{"modules":[{"0":true,"1":true,"2":true,"-1":false,"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"}]},"mdm":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"MDM Enrollment"}]}},"roleDescription":"sadasd"}'

▼ Show full

Sample Request Body

Create role with full module structure across desktopCentral, osd, browserSecurity, SecurityAddOn, and mdm.

Copied!

  {
    "roleName": "testrole",
    "roleDetails": {
      "osd": {
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "value": "OSD Imaging"
          }
        ]
      },
      "desktopCentral": {
        "modules": [
          {
            "0": true,
            "1": true,
            "2": true,
            "-1": false,
            "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"
          }
        ]
      },
      "mdm": {
        "modules": [
          {
            "0": false,
            "1": false,
            "2": false,
            "-1": true,
            "value": "MDM Enrollment"
          }
        ]
      }
    },
    "roleDescription": "sadasd"
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON object

Hide Sub-Attributes

roleIdstring

Unique identifier assigned to the newly created role.

roleNamestring

Name of the newly created role.

messagestring

Success message confirming role creation.

successCodestring

Success code for the role creation 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 creation success response.

Copied!

  {
    "roleId": "97913000000566015",
    "roleName": "Security Auditor",
    "message": "New role Security Auditor has been added successfully.",
    "successCode": "40015"
  }

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