Retrieve a specific role

Use the Return Specific Role API to retrieve a specific role in the Control Room.

Prerequisites

View Roles
Users who have view roles permissions can retrieve details of a specific role.
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/{ID}.
  • Method: GET.
  • Use the Swagger definition files installed with your Control Room to test the APIs. View the available Swagger APIs at: http://<your_control_room_url>/swagger/.
  • You can also use a REST client to complete this task.

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 GET as the method.
  3. In the request URL, add a role ID you want to retrieve.
    GET http://<your_control_room_url>/v1/usermanagement/roles/17
    • In a REST client, click SEND.
    • In the Swagger interface, click Execute.

    Response body:

    {
  "id": 17,
  "createdBy": 4,
  "createdOn": "2019-11-20T18:26:37Z",
  "updatedBy": 4,
  "updatedOn": "2019-11-20T18:26:37Z",
  "tenantId": 1,
  "version": 0,
  "status": "Active",
  "description": "Created a Role for Bot running",
  "name": "DocBotRoleMD1",
  "accessRestriction": null,
  "permissions": [{
    "id": 134,
    "createdBy": 0,
    "createdOn": "2019-12-05T00:03:05Z",
    "updatedBy": 0,
    "updatedOn": "2019-12-05T00:03:05Z",
    "tenantId": 1,
    "version": 0,
    "status": null,
    "action": "viewuserbasic",
    "resourceId": null,
    "resourceType": "usermanagement"
  }],
  "countPrincipals": 0,
  "principals": [{
    "id": 16,
    "createdBy": 4,
    "createdOn": "2019-11-22T20:52:35Z",
    "updatedBy": 4,
    "updatedOn": "2019-11-22T20:52:35Z",
    "tenantId": 1,
    "version": 0,
    "status": "Active",
    "username": "docs_md_admin",
    "description": "Created a user with admin rights",
    "deleted": false,
    "disabled": false,
    "email": "aamd@md.com",
    "firstName": "Docs_AAMD1",
    "lastName": "Docs_AAMD1",
    "autoLoginEnabled": true,
    "emailVerified": true,
    "clientRegistered": false,
    "passwordSet": false,
    "questionsSet": false,
    "activeDirectory": false
  }]
}
    Parameter name Description
    id System-generated role ID number.
    createdBy System-generated user ID of an admin user who created a role.
    updatedBy System-generated user ID of an admin user who updated a role.
    tenantID System-generated ID number of an active user.
    version System-generated version number for a new role. Each time a role is updated, the version number is incremented.
    accessRestriction Lists access restrictions for a specific role.
    Permissions Lists role permissions.
    countPrincipals Total number of active directory principal users.
    principals Lists active directory principal users.
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 GET "http://<your_control_room_url>/v1/usermanagement/roles/31" 
-H "accept: application/json" 
-H "X-Authorization: <authentication_token>" 
-H "Content-Type: application/json" -d "{17}"