Update an existing role

Use the Update Existing Role API to update an existing role in the Control Room.

Prerequisites

Edit Roles
Users who have edit roles permissions can update a 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}.

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

  • Method: PUT.
  • 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 PUT as the method.
  3. In the request URL, add a role ID you want to update.
    PUT http://<your_control_room_url>/v1/usermanagement/roles/37

    Request body:

     {
      "id": null,
      "name": "viewRoles-Docs1",
      "accessRestriction": null,
      "permissions": [{
        "id": 59,  
        "action": "ManageCredentials",
        "resourceId": null,
        "resourceType": "credentials"
      },  {
        "id": 134,
        "action": "ViewUserBasic",
        "resourceId": null,
        "resourceType": "UserManagement"
      }],
      "countPrincipals": 0,
      "principals": [{
        "id": 21
      }]
    }
  4. Send the request.
    • In Swagger, click Execute.
    • In a REST client, click SEND.

    Response body:

    {
      "id": 37,
      "createdBy": 4,
      "createdOn": "2019-12-17T03:24:22Z",
      "updatedBy": 36,
      "updatedOn": "2019-12-18T00:13:27Z",
      "tenantId": 1,
      "version": 20,
      "status": "Active",
      "description": null,
      "name": "viewRoles-Docs1",
      "accessRestriction": null,
      "permissions": [{
        "id": 59,
        "createdBy": 0,
        "createdOn": "2019-10-03T23:53:47Z",
        "updatedBy": 0,
        "updatedOn": "2019-10-03T23:53:47Z",
        "tenantId": 1,
        "version": 0,
        "status": null,
        "action": "managecredentials",
        "resourceId": null,
        "resourceType": "credentials"
      }, {
        "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": 21,
        "createdBy": 4,
        "createdOn": "2019-11-24T17:41:37Z",
        "updatedBy": 4,
        "updatedOn": "2019-12-17T03:25:47Z",
        "tenantId": 1,
        "version": 11,
        "status": "Active",
        "username": "docs-bot",
        "description": "Basic bot and MetaBot designer",
        "deleted": false,
        "disabled": false,
        "email": "tm@aa.com",
        "firstName": "",
        "lastName": "",
        "autoLoginEnabled": false,
        "emailVerified": true,
        "clientRegistered": true,
        "passwordSet": true,
        "questionsSet": true,
        "activeDirectory": false
      }]
    }
    Parameter name Description
    id System-generated role ID number.
    createdBy System-generated role ID number of an admin user who created a role.
    updatedBy System-generated role ID number 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.
    status An existing role state: active or disabled.
    accessRestriction Lists access restrictions for a specific role.
    Permissions Lists role permissions.
    countPrincipals The total number of the active directory principal users.
    principals Lists the 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 PUT "http://<your_control_room_url>/v1/usermanagement/roles/37" 
-H "accept: application/json" 
-H "X-Authorization: <authentication_token>" 
-H "Content-Type: application/json" -d "'{
  "id": null,
  "name": "viewRoles-Docs1",
  "accessRestriction": null,
  "permissions": [{
    "id": 59,  
    "action": "ManageCredentials",
    "resourceId": null,
    "resourceType": "credentials"
  },  {
    "id": 134,
    "action": "ViewUserBasic",
    "resourceId": null,
    "resourceType": "UserManagement"
  }],
  "countPrincipals": 0,
  "principals": [{
    "id": 21
  }]
}'