Search for roles

Use the Search for Roles API to search for roles based on a date filter, sorting, and pagination.

Prerequisites

View Roles
Users who have view roles permissions can retrieve all roles.
JSON Web Token (JWT)
All Control Room APIs require a JSON Web Token (JWT) to access the APIs. Generate an authentication token using the Authentication API. See Enterprise 11 Authentication API.
  • URL: http://<your_control_room_url>/v1/usermanagement/roles/list

    Replace the content in the angle brackets with your Control Room URL.

  • Method: POST

Procedure

  1. Add an authentication token to the request header.
    Use the Authentication API to generate a JSON Web Token. See Enterprise 11 Authentication API.
  2. Select POST as the method.
    POST http://<your_control_room_url>/v1/usermanagement/roles/list
    Apply filters to perform basic conditional queries and pagination control for processing web pages. There are three basic features related to filtering: filtering conditions, sorting columns, and pagination parameters. See the Filters in an API request body.

    The following request sets pagination filters, such as page: offset and length.

  3. Send the request.
    • In a REST client, click SEND.
    • In the Swagger interface, click Execute.

    Request body:

    {
"sort": [
  {
   "field": "name",
   "direction": "asc"
  }
],
"filter": {
  "operator": "substring",
  "value": "sample",
  "field": "name"
},
"fields": [],
"page": {
  "offset": 0,
  "total": 23,
  "totalFilter": 23,
  "length": 200
}
}

    Response body:

    The response in this example retrieves all roles which includes the word sample in the name field.

    {
"page": {
  "offset": 0,
  "total": 37,
  "totalFilter": 3
},
"list": [
  {
   "id": 40,
   "name": "API_Roles_sample",
   "description": "",
   "countPrincipals": 0,
   "version": 0,
   "createdBy": 36,
   "createdOn": "2019-12-18T21:02:49.087Z",
   "updatedBy": 36,
   "updatedOn": "2019-12-18T21:02:49.087Z"
  },
  {
   "id": 39,
   "name": "API_sample",
   "description": "",
   "countPrincipals": 0,
   "version": 0,
   "createdBy": 36,
   "createdOn": "2019-12-18T21:01:58.383Z",
   "updatedBy": 36,
   "updatedOn": "2019-12-18T21:01:58.383Z"
  },
  {
   "id": 38,
   "name": "sample_1",
   "description": "",
   "countPrincipals": 0,
   "version": 0,
   "createdBy": 36,
   "createdOn": "2019-12-18T21:01:12.623Z",
   "updatedBy": 36,
   "updatedOn": "2019-12-18T21:01:12.623Z"
  }
]
}
Note: You can also run REST requests from a command terminal. The following is a curl request example. This example is formatted for readability. Replace the text inside the angle brackets, <authentication_token>, with your authentication token.
curl -X POST "http://<your_control_room_url>/v1/usermanagment/roles/list" 
-H "accept: application/json" 
-H "X-Authorization: <authentication_token>" 
-H "Content-Type: application/json" -d "{
  {
"sort": [
  {
   "field": "name",
   "direction": "asc"
  }
],
"filter": {
  "operator": "substring",
  "value": "sample",
  "field": "name"
},
"fields": [],
"page": {
  "offset": 0,
  "total": 23,
  "totalFilter": 23,
  "length": 200
}
}'