Role endpoints in the REST API

The following section provides a list of supported endpoints for roles and details about running these endpoints. For more information about roles, see Roles-and-permissions.

Before you run an endpoint, you must authenticate yourself. For more information, see Access-and-authentication-for-the-REST-API.


Roles

You can perform the following operations related to roles: 

POST /ims/api/v1/roles
Create a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "composite": false,
 "default_role": false,
 "description": "string",
 "name": "string"
}
Example request body
{
 "composite": false,
 "default_role": false,
 "description": "Operator role with view permissions only",
 "name": "Mark Operator"
}
Parameters


Successful response
{
 "role_id": "880083129358647"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T13:04:01.606391Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "name Mark Operator already exists."
}
GET /ims/api/v1/roles
Get all roles under a tenant
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles
Request URL with optional parameters
 https://<BMC Helix Portal URL>/ims/api/v1/roles?page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=asc
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters


Successful response
{
 "records": [
    {
     "role_id": "559668411572956",
     "name": "Administrator",
     "description": "All permissions for all applications",
     "system_object": true,
     "composite": false,
     "default_role": false
    },
    {
     "role_id": "231029950887169",
     "name": "RBACAdmin",
     "description": "All permissions for Users Management",
     "system_object": true,
     "composite": false,
     "default_role": false
    },
    {
     "role_id": "928062612479169",
     "name": "Reporting Admin",
     "description": "Reporting Admin",
     "system_object": true,
     "composite": false,
     "default_role": false
    },
    {
     "role_id": "506411079685279",
     "name": "Reporting Editor",
     "description": "Reporting Editor",
     "system_object": true,
     "composite": false,
     "default_role": false
    },
    {
     "role_id": "902074252661131",
     "name": "Reporting Viewer",
     "description": "Reporting Viewer",
     "system_object": true,
     "composite": false,
     "default_role": false
    }
  ],
 "_metadata": {
   "page": 0,
   "records_per_page": 1000,
   "page_count": 1,
   "total_count": 5
  }
}
DELETE /ims/api/v1/roles/{id}
Delete a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters


Successful response
{
"message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T13:19:08.030982Z",
 "code": 1300,
 "message": "Role not found.",
 "error": "Role with id :949723054752721 not found."
}
GET /ims/api/v1/roles/{id}
Get details of a specific role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response

Scenario 1: No objects are assigned to the role:

{
 "role_id": "949723054752722",
 "name": "abcde",
 "description": "string",
 "system_object": false,
 "composite": false,
 "default_role": false,
 "groups": [],
 "permissions": [],
 "roles": [],
 "users": []
}

Scenario 2: Objects are assigned to a role:

{
 "role_id": "928062612479169",
 "name": "Reporting Admin",
 "description": "Reporting Admin",
 "system_object": true,
 "composite": false,
 "default_role": false,
 "groups": [],
 "permissions": [
   {
     "permission_id": "reporting.dashboards_permissions.admin"
   }
  ],
 "roles": [],
 "users": [
   {
     "user_id": "549720570762485"
   }
  ]
}
PATCH /ims/api/v1/roles/{id}
Update general details of a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "default_role": false,
 "description": "string",
 "name": "string"
}
Example request body
{
 "default_role": false,
 "description": "This is a new admin role",
 "name": "Admin"
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
"responseTimeStamp": 1600423987155,
"statusCode": "ROLENAME_ALREADY_EXIST",
"statusMsg": "[Failed to create role, entry with same name already exists]",
"resourceId": null,
"resourceName": null,
"failedResource": null
}
POST /ims/api/v1/roles/search
Search for roles
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/roles/search
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/roles/search?page={pageNumber}&size={records}&orderBy=created_date_time&sortOrder=asc
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "filters": [
   {
     "field": "string",
     "values": [
       "string"
      ]
   }
  ]
}
Example request body
{
 "filters": [
   {
     "field": "*",
     "values": ["role_name1"
        ]
   }
  ]
}
Parameters
Successful response
{
  "records":    [
           {
        "role_id": "903310426408451",
        "name": "role_name1FegD6",
        "description": "testing",
        "system_object": false,
        "composite": true,
        "default_role": true
     },
           {
        "role_id": "880429686585810",
        "name": "role_name123FegD6",
        "description": "testing",
        "system_object": false,
        "composite": false,
        "default_role": false
     }
   ],
  "_metadata":    {
     "page": 0,
     "records_per_page": 1000,
     "page_count": 1,
     "total_count": 2
  }
}
Unsuccessful response

Scenario 1: You search by the role ID instead of the role name or description.

{
  "records": [],
  "_metadata":    {
     "page": 0,
     "records_per_page": 1000,
     "page_count": 0,
     "total_count": 0
  }
}

Scenario 2: You pass more than one value in a search.

{
  "timestamp": "2020-12-31T19:43:11.060242Z",
  "code": 2300,
  "message": "BAD_REQUEST",
  "error": "Only one value for search is supported."
}

Scenario 2: You search with any value other than "*" as the field parameter value.

{
  "timestamp": "2020-12-31T19:43:57.375969Z",
  "code": 2300,
  "message": "BAD_REQUEST",
  "error": "Unsupported search field: role_name"
}



Role associations

You can perform the following operations related to the users, user groups, and permissions associated with a role and the roles associated with a composite role: 

PATCH /ims/api/v1/roles/{id}/groups
Update groups associated with a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/groups
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "groups": [
   {
     "id": "string",
     "op": "string"
   },
   {
     "id": "string",
     "op": "string"
   }
  ]
}
Example request body
{
 "groups": [
   {
     "id": "907575313926650",
     "op": "add"
   },
   {
     "id": "564275313234650",
     "op": "remove"
   }
  ]
}


Parameters
Successful response
{
 "message": "SUCCESS"
}
PUT /ims/api/v1/roles/{id}/groups
Replace groups associated with a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/groups
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "groups": [
   {
     "group_id": "string"
   },
   {
     "group_id": "string"
   }
  ]
}
Example request body
{
 "groups": [
   {
     "group_id": "907575313926650"
   },
   {
     "group_id": "564275313234650"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
GET /ims/api/v1/roles/{id}/permissions
Get all permissions of a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/permissions
Request URL with optional parameters
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/permissions?includeCompositeRole={true/false}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response (with includeCompositeRole=false)
[
 {
   "permission_id": "ims.users.modify"
 },
 {
   "permission_id": "ims.roles.list"
 },
 {
   "permission_id": "ims.users.create"
 },
 {
   "permission_id": "ims.access_keys.list"
 },
 {
   "permission_id": "ims.users.access_keys_delete"
 },
 {
   "permission_id": "ims.roles.delete"
 },
 {
   "permission_id": "ims.roles.modify"
 },
 {
   "permission_id": "ims.access_keys.create"
 },
 {
   "permission_id": "ims.permissions.list"
 },
 {
   "permission_id": "ims.users.delete"
 },
 {
   "permission_id": "ims.access_keys.delete"
 },
 {
   "permission_id": "ims.roles.create"
 },
 {
   "permission_id": "ims.users.access_keys_create"
 }
]
Unsuccessful response (with includeCompositeRole=false)
{
 "timestamp": "2020-12-18T10:40:54.582697Z",
 "code": 1300,
 "message": "Role not found.",
 "error": "Role ID 400348018016 could not be found. Verify that the role ID specified is correct."
}
PATCH /ims/api/v1/roles/{id}/permissions
Update permissions associated with a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/permissions
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "permissions": [
   {
     "id": "string",
     "op": "string"
   },
   {
     "id": "string",
     "op": "string"
   }
  ]
}
Example request body


{
 "permissions": [
   {
     "id": "ims.permissions.read",
     "op": "add"
   },
   {
     "id": "ims.permissions.put",
     "op": "remove"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-12T07:31:08.393769Z",
 "code": 1300,
 "message": "Role not found.",
 "error": "Role with id :681559887017412 not found."
}
{
 "timestamp": "2020-10-12T07:34:04.190024Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "permission_id ims.permissions.read1 does not exist."
}
PUT /ims/api/v1/roles/{id}/permissions
Replace permissions associated with a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/permissions
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "permissions": [
   {
     "permission_id": "string"
   },
{
     "permission_id": "string"
   }
  ]
}
Example request body
{
 "permissions": [
   {
     "permission_id": "ims.permissions.read"
     },
     {
     "permission_id": "ims.permissions.create"
     }
    ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-12T10:09:24.421465Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "permission_id ims.core.create does not exist."
}
PATCH /ims/api/v1/roles/{id}/roles
Update roles associated with a composite role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/roles
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "roles": [
   {
     "id": "string",
     "op": "string"
   },
   {
     "id": "string",
     "op": "string"
   }
  ]
}
Example request body
{
 "roles": [
   {
     "id": "134948174005733",
     "op": "add"
   },
   {
     "id": "229948123005786",
     "op": "remove"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-12T11:32:14.815283Z",
 "code": 1300,
 "message": "Role not found.",
 "error": "Role with id :543131979140958 not found."
}
PUT /ims/api/v1/roles/{id}/roles
Replace roles associated with a composite role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/roles
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "roles": [
   {
     "role_id": "string"
   },
   {
     "role_id": "string"
   }
  ]
}
Example request body
{
 "roles": [
   {
     "role_id": "681559887017411"
   },
   {
     "role_id": "134948174005733"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
PATCH /ims/api/v1/roles/{id}/users
Update users associated with a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/users
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "users": [
   {
     "id": "string",
     "op": "string"
   },
   {
     "id": "string",
     "op": "string"
   }
  ]
}
Example request body
{
 "users": [
   {
     "id": "811597463253119",
     "op": "add"
   },
   {
     "id": "765597481253900",
     "op": "remove"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-12T14:01:43.907876Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "user_id 111597463203120 does not exist."
}
PUT /ims/api/v1/roles/{id}/users
Replace users associated with a role
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}/users
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "users": [
   {
     "user_id": "string"
   },
   {
     "user_id": "string"
   }
  ]
}
Example request body
{
 "users": [
   {
     "user_id": "907575313926650"
   },
   {
     "user_id": "200755400921234"
   }
  ]
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-12T14:30:29.239140Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "user_id 811597463253120 does not exist."
}
POST /ims/api/v1/roles/user_mappings
Update users associated with roles
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/roles/user_mappings
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "mappings": [
   {
     "actions": [
       {
         "op": "string",
         "user_ids": [
           "string"
          ]
       }
      ],
     "role_id": "string"
   }
  ]
Example request body
{
 "mappings": [
   {
     "actions": [
       {
         "op": "add",
         "user_ids": [
           "628553027974274"
          ]
       }
      ],
     "role_id": "721343778993755"
   }
  ]
}
Parameters


Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response

Scenario 1: You specify a role that does not exist.

{
 "timestamp": "2021-06-14T13:22:57.128547Z",
 "code": 2300,
 "message": "BAD_REQUEST",
 "error": "Some roleIds are missing, please send correct roleIds."
}

Scenario 2: You specify one or more users that do not exist.

{
 "timestamp": "2021-06-14T13:23:44.126419Z",
 "code": 2300,
 "message": "BAD_REQUEST",
 "error": "Some userIds are missing, please send correct userIds."
}

Scenario 3: You do not specify a mandatory field.

{
 "timestamp": "2021-06-14T13:25:38.848751Z",
 "code": 2300,
 "message": "BAD_REQUEST",
 "error": "At least one action with valid payload should be present. Please check the documentation for correct request body."
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*