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."
}