# 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`

## Request URL

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

## Scope

`DesktopCentralCloud.Admin.CREATE`

## Header

`Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52`

## Request Parameters

### Request Headers

- **accept** `string` — **Mandatory**
  - `application/addRole.v1+json`
  - Specifies the expected response format. Set to application/addRole.v1+json to receive the role creation response in JSON format.
- **content-type** `string` — **Mandatory**
  - `application/addRole.v1+json`
  - 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`
  - **roleName** `string` — **Mandatory**
    - Unique name for the new role. Supports alphanumeric characters, spaces, and special characters. Maximum 100 characters.
  - **roleDescription** `string` — **Mandatory**
    - Optional description of the role's purpose and access level. Maximum 250 characters.
  - **roleDetails** `JSON Object` — **Mandatory**
    - Product-keyed object mapping each product name to its module and feature permission details for this role.

## Sample Request

```curl
curl --request POST \
  --url https://appdomains/emsapi/roles \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'accept: application/addRole.v1+json' \
  --header 'content-type: application/addRole.v1+json' \
  --data '{"roleName":"testrole","roleDetails":{},"roleDescription":"sadasd"}'
```

## Sample Request Body

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

```json
{
  "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"
}
```

## Response Parameters

### HTTP Code 200

Response Body — `application/json`

- `JSON Object`
  - **roleId** `string`
    - Unique identifier assigned to the newly created role.
  - **roleName** `string`
    - Name of the newly created role.
  - **message** `string`
    - Success message confirming role creation.
  - **successCode** `string`
    - Success code for the role creation operation.

### HTTP Code 412

Response Body — `application/json`

- `JSON Object`
  - **errorCode** `string`
    - Application-specific error code indicating the reason for the request failure.
  - **errorMsg** `string`
    - Error message describing the cause of the error.

## Possible Response Codes

- **200** `HTTP code`
- **412** `HTTP code`

## Sample Response: HTTP 200

Role creation success response.

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

## Sample Response: HTTP 412

The Role Name already exists. Please choose a different name.

```json
{
  "errorCode": "40018",
  "errorMsg": "Role name Product Admin already exists."
}
```

## Rate Limits

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