List roles

Use the List Roles API to retrieve a list of roles in the Control Room. The endpoint supports pagination, sorting, and filtering.

Request

POST http://{{ControlRoomURL}}/v1/usermanagement/roles/list

Header: X-Authorization <<authentication token>>

All API calls must contain an authentication token in the request header. Use the Authentication API to generate a JSON web token. See Authentication API.

Request body without filters:

{
   "sort":[
      {
         "field":"name",
         "direction":"asc"
      }
   ],
   "filter":{
      
   },
   "page":{
      "offset":0,
      "total":100,
      "totalFilter":100,
      "length":200
   }
}

Request body with filters:

{
   "sort":[
      {
         "field":"name",
         "direction":"asc"
      }
   ],
   "filter":{
      "operator":"and",
      "operands":[
         {
            "operator":"substring",
            "field":"name",
            "value":"Device"
         },
         {
            "operator":"gt",
            "field":"createdOn",
            "value":"2022-02-01T00:00:00.989Z"
         },
         {
            "operator":"lt",
            "field":"createdOn",
            "value":"2022-03-20T23:00:00.123Z"
         }
      ]
   },
   "page":{
      "offset":0,
      "total":100,
      "totalFilter":100,
      "length":200
   }
   }

Request Parameters


Parameter	Type	Required	Description
sort	Array	No	By default, search results are sorted in descending order with respect to their ids. An alternative sorting is specified using the sort query parameter. Enter the field by which you want to sort along with the direction `asc` (ascending) or `desc` (descending).
filter	Object	No	Filters the result.
page	Object	No	The page object allows you to get the desired pages.

For more information on Filtering, Pagination, and Sorting, see Filtering, pagination, and sorting.

Response

{
    "page": {
        "offset": 0,
        "total": 21,
        "totalFilter": 1
    },
    "list": [
        {
            "id": 24,
            "name": "Device_admin",
            "description": "This is a device admin role",
            "countPrincipals": 1,
            "version": 1,
            "createdBy": 1,
            "createdOn": "2022-03-17T19:32:20.620Z",
            "updatedBy": 1,
            "updatedOn": "2022-03-24T02:20:13.787Z",
            "systemRole": false
        }
    ]
}

Response Parameters


Parameter	Type	Description
offset	Integer	The starting list offset, used for pagination.
total	Integer	Total number of records.
totalFilter	Integer	Number of records after applying the filter.
List	Array	The array of List roles object.
List roles object
id	Integer	The unique Id of a specific role.
name	String	Name of role.
description	String	Description of role.
countPrincipals	Integer	Count of Principals (users) who are granted with this role.
version	Integer	Version of the role instance.
createdBy	Integer	Id of the user who created the role.
createdOn	String	The creation timestamp of the role.
updatedBy	Integer	Id of the user who made a latest update to the role.
updatedOn	String	The latest update timestamp of the role.
systemRole	Boolean	Flag to indicate if this role is system role or not.

Note: You can view the Control Room APIs in the Community Edition, but API functionality is limited. You need a licensed Automation 360 Edition to access the full functionality of the APIs.

The REST API responds to each request with an HTTP response code. For response codes, see API response codes.