---
title: "Role"
slug: "server-api-global-setting-role"
updated: 2022-06-16T08:28:13Z
published: 2022-06-16T08:28:13Z
canonical: "developer.comm100.com/server-api-global-setting-role"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developer.comm100.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Role

## Role

You need the Manage Agent & Agent Roles permission to manage roles.

- `Roles` - Roles Manage
  - `GET global/roles` - [Get the list of Roles](/docs/server-api-global-setting-role#get-the-list-of-roles)
  - `GET global/roles/{id}` - [Get a single Role](/docs/server-api-global-setting-role#get-a-single-role)
  - `POST global/roles` - [Create a new Role](/docs/server-api-global-setting-role#create-a-new-role)
  - `PUT global/roles/{id}` - [Update the Role](/docs/server-api-global-setting-role#update-the-role)
  - `DELETE global/roles/{id}` - [Remove the Role](/docs/server-api-global-setting-role#remove-the-role)

### Role JSON Format

Role is represented as simple flat JSON objects with the following keys:

| Name | Type | Description |
| --- | --- | --- |
| `id` | guid | Id of the role. |
| `name` | string | Name of the role. |
| `description` | string | Description of the role. |
| `type` | string | "Administrators" and "AllAgents" are the system role types. They cannot be deleted.Allowed values are "Administrators", "AllAgents", "Custom". |
| `agentIds` | array | The selected agents for this role.If not offered, will use role identifier of "AllAgents" as default. |
| `permissionIds` | array | Permissions assigned to this role. |

### Get the list of Roles

`GET global/roles`

- #### Parameters:

| Name | Type | in | Required | Description |
| --- | --- | --- | --- | --- |
| `include` | string | query | no | Allowed values are "agent", "permission". |

- #### Response:

An array of [Role](/docs/server-api-global-setting-role#role-json-format)

- #### Example

Sample Request:

```
curl https://api11.comm100.io/v4/global/roles \ 
    -X 'GET' \ 
    -H 'Authorization: Bearer {access_token}' \
```

Response:

HTTP/1.1 200 OK

```
[
  {
      "id": "c8448a05-ede0-4adc-bb43-6b1ee3977b9c",
      "name": "Pre-sale",
      "description": "Pre-sale role",
      "type": "Custom",
      "agentIds": [
          "3FA2EF45-7D46-EB11-8100-00155D081D0B"
      ],
      "permissionIds": [
          "4,5"
      ]
  }
]
```

### Get a single Role

`GET global/roles/{id}`

- #### Parameters:

| Name | Type | in | Required | Description |
| --- | --- | --- | --- | --- |
| `include` | string | query | no | Allowed values are "agent", "permission". |

- #### Response:

[Role](/docs/server-api-global-setting-role#role-json-format)

- #### Example

Sample Request:

```
curl https://api11.comm100.io/v4/global/roles/c8448a05-ede0-4adc-bb43-6b1ee3977b9c \ 
    -X 'GET' \ 
    -H 'Authorization: Bearer {access_token}' \
```

Response:

HTTP/1.1 200 OK

```
{
  "id": "c8448a05-ede0-4adc-bb43-6b1ee3977b9c",
  "name": "Pre-sale",
  "description": "Pre-sale role",
  "type": "Custom",
  "agentIds": [
      "3FA2EF45-7D46-EB11-8100-00155D081D0B"
  ],
  "permissionIds": [
      "4,5"
  ]
}
```

### Create a new Role

`POST global/roles`

- #### Parameters:

| Name | Type | in | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | string | body | yes | Name of the role. |
| `description` | string | body | no | Description of the role. |
| `type` | string | body | no | "Administrators" and "AllAgents" are the system role types. They cannot be deleted.Allowed values are "Administrators", "AllAgents", "Custom". |
| `agentIds` | array | body | no | The selected agents for this role.If not offered, will use role identifier of "AllAgents" as default. |
| `permissionIds` | array | body | no | Permissions assigned to this role. |

- #### Response:

[Role](/docs/server-api-global-setting-role#role-json-format)

- #### Example

Sample Request:

```
curl https://api11.comm100.io/v4/global/roles \ 
    -X 'POST' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \ 
    -D '{"name":"Pre-sale","description":"Pre-sale role","type":"Custom"}'
```

Response:

HTTP/1.1 201 Created

```
{
  "id": "c8448a05-ede0-4adc-bb43-6b1ee3977b9c",
  "name": "Pre-sale",
  "description": "Pre-sale role",
  "type": "Custom",
  "agentIds": [
      "3FA2EF45-7D46-EB11-8100-00155D081D0B"
  ],
  "permissionIds": [
      "4,5"
  ]
}
```

### Update the Role

`PUT global/roles/{id}`

- #### Parameters:

| Name | Type | in | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | string | body | yes | Name of the role. |
| `description` | string | body | no | Description of the role. |
| `type` | string | body | no | "Administrators" and "AllAgents" are the system role types. They cannot be deleted.Allowed values are "Administrators", "AllAgents", "Custom". |
| `agentIds` | array | body | no | The selected agents for this role.If not offered, will use role identifier of "AllAgents" as default. |
| `permissionIds` | array | body | no | Permissions assigned to this role. |

- #### Response:

[Role](/docs/server-api-global-setting-role#role-json-format)

- #### Example

Sample Request:

```
curl https://api11.comm100.io/v4/global/roles/c8448a05-ede0-4adc-bb43-6b1ee3977b9c \ 
    -X 'PUT' \ 
    -H 'Authorization: Bearer {access_token}' \ 
    -H 'Content-Type: application/json' \ 
    -D '{"name":"Pre-sale","description":"Pre-sale role","type":"Custom"}'
```

Response:

HTTP/1.1 200 OK

```
{
  "id": "c8448a05-ede0-4adc-bb43-6b1ee3977b9c",
  "name": "Pre-sale",
  "description": "Pre-sale role",
  "type": "Custom",
  "agentIds": [
      "3FA2EF45-7D46-EB11-8100-00155D081D0B"
  ],
  "permissionIds": [
      "4,5"
  ]
}
```

### Remove the Role

`DELETE global/roles/{id}`

- #### Parameters:

No Parameters

- #### Response:

No Content

- #### Example

Sample Request:

```
curl https://api11.comm100.io/v4/global/roles/c8448a05-ede0-4adc-bb43-6b1ee3977b9c \ 
    -X 'DELETE' \ 
    -H 'Authorization: Bearer {access_token}' \
```

Response:

HTTP/1.1 204 No Content