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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
composite | body | Indication of whether the role must be a composite role. Valid values:
| no | boolean |
default_role | body | Indication of whether the role must be created as an out-of-the-box role. Valid values:
| no | boolean |
description | body | Description of the role. | yes | string |
name
| body | Name of the role. | yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
page | query | Page number from which you want to retrieve roles. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter. | no | integer |
size | query | Total number of records that you want to retrieve from a page. Default: 1000 records | no | integer |
orderBy | query | Column on which you want to sort. Valid values:
| no | string |
sortOrder | query | Sort order of the details to be retrieved. Valid values:
| no | string |
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}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role that you want to delete. | yes | string |
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}
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/roles/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role for which you want to retrieve details. | yes | string |
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}
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
ID | path | ID of the role that you want to update. | yes | string |
default_role | body | Indication of whether the role must be available to all users under the tenant. Valid values:
| no | boolean |
description | body | Updated description of the role. | no | string |
name
| body | Updated name of the role. | yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
page | query | Page number from which you want to retrieve roles. Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter. | no | integer |
size | query | Total number of records that you want to retrieve from a page. Default: 1000 records | no | integer |
orderBy | query | Column on which you want to sort. Valid values:
| no | string |
sortOrder | query | Sort order of the details to be retrieved. Valid values:
| no | string |
field | body | Field by which you want to search roles. At one time, you can search by the role name, description, or the role ID. If you want to perform a global search in all the fields, provide an asterisk (*) as the value. Valid values:
| Yes | string |
values | body | Value with which you want to search the access keys. You can pass a comma-separated list of multiple values for all the valid fields except when you use an asterisk (*) as the field. | Yes | Array[string] |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role that you want to update. | yes | string |
id | body | ID of the user group that you want to add or remove. | yes | string |
op | body | Type of operation that you want to perform. Valid values:
| yes | string |
Successful response
{
"message": "SUCCESS"
}
PUT /ims/api/v1/roles/{id}/groups
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role in which you want to replace user groups. | yes | string |
group_id | body | ID of the user group that you want to assign to the role. | yes | string |
Successful response
{
"message": "SUCCESS"
}
GET /ims/api/v1/roles/{id}/permissions
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role from which you want to retrieve the permissions. | yes | string |
includeCompositeRole | query | Indication of whether to retrieve details of a composite role. Valid values:
| no | boolean |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role that you want to update. | yes | string |
id | body | ID of the permission that you want to add or remove. | yes | string |
op | body | Type of operation that you want to perform. Valid values:
| yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role in which you want to replace permissions. | yes | string |
permission_id | body | ID of the permission that you want to assign to the role. | yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the composite role that you want to update. | yes | string |
id | body | ID of the role that you want to add or remove. | yes | string |
op | body | Type of operation that you want to perform. Valid values:
| yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the composite role in which you want to replace roles. | yes | string |
role_id | body | ID of the role that you want to assign to the composite role. | yes | string |
Successful response
{
"message": "SUCCESS"
}
PATCH /ims/api/v1/roles/{id}/users
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role that you want to update. | yes | string |
id | body | ID of the user that you want to add or remove. | yes | string |
op | body | Type of operation that you want to perform. Valid values:
| yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
id | path | ID of the role in which you want to replace users. | yes | string |
user_id | body | ID of the user that you want to assign to the role. | yes | string |
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
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
Name | Located in | Description | Mandatory | Schema |
---|---|---|---|---|
op | body | Type of operation that you want to perform. Valid values:
Note: If you specify all the operations in the same request body, the API evaluates and runs these operations by using the following precedence order. Multiple expressions of the same operation are run together. For example, all the expressions for adding users are performed together.
| yes | string |
user_ids | body | Comma-separated list of user IDs to use for performing the operation. | yes | string |
role_id | body | ID of the role that you want to update. | yes | string |
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."
}
Comments
Log in or register to comment.