×
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')
 
 
BMC Helix Portal Performing role-based access control with REST API

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


NameLocated inDescriptionMandatorySchema
compositebody

Indication of whether the role must be a composite role.

Valid values:

  • true
  • (default) false
noboolean
default_rolebody

Indication of whether the role must be created as an out-of-the-box role.

Valid values:

  • true
  • (default) false
noboolean
descriptionbodyDescription of the role.yesstring
name
bodyName of the role.yesstring

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


NameLocated inDescriptionMandatorySchema
pagequery

Page number of the User access > Roles and permissions page displayed on the console from where you want to retrieve details.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Column on which you want to sort.

Valid values: 

  • role_id
  • name
  • description
  • system_object
  • composite
  • default_role
  • (Default) created_date_time
nostring
sortOrderquery

Sort order of the details to be retrieved.

Valid values:

  • (Default) asc
  • desc
nostring

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


NameLocated inDescriptionMandatorySchema
idpathID of the role that you want to delete.yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the role for which you want to retrieve details.yesstring

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

NameLocated inDescriptionMandatorySchema
IDpathID of the role that you want to update.yesstring
default_rolebody

Indication of whether the role must be available to all users under the tenant.

Valid values:

  • true
  • (default) false
noboolean
descriptionbodyUpdated description of the role.nostring
name
bodyUpdated name of the role.yesstring

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

NameLocated inDescriptionMandatorySchema
pagequery

Page number of the User access > Roles and permissions page displayed on the console from where you want to retrieve details.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Column on which you want to sort.

Valid values: 

  • role_id
  • name
  • description
  • system_object
  • composite
  • default_role
  • (Default) created_date_time
nostring
sortOrderquery

Sort order of the details to be retrieved.

Valid values:

  • (Default) asc
  • desc
nostring
fieldbody

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 asterisk (*) as the value.

Valid values:

  • name
  • description
  • role_id
  • * 
Yesstring
valuesbody

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 asterisk (*) as the field.

YesArray[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
 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

NameLocated inDescriptionMandatorySchema
idpathID of the role that you want to update.yesstring
idbodyID of the user group that you want to add or remove.yesstring
opbody

Type of operation that you want to perform.

Valid values:

  • add
  • remove
yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the role in which you want to replace user groups.yesstring
group_idbodyID of the user group that you want to assign to the role.yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the role from which you want to retrieve the permissions.yesstring

includeCompositeRole

query

Indication of whether to retrieve details of a composite role.

Valid values:

  • true
  • (default) false
noboolean

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

NameLocated inDescriptionMandatorySchema
idpathID of the role that you want to update.yesstring
idbody

ID of the permission that you want to add or remove.

yesstring
opbody

Type of operation that you want to perform.

Valid values:

  • add
  • remove
yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the role in which you want to replace permissions.yesstring
permission_idbodyID of the permission that you want to assign to the role.yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the composite role that you want to update.yesstring
idbodyID of the role that you want to add or remove.yesstring
opbody

Type of operation that you want to perform.

Valid values:

  • add
  • remove
yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the composite role in which you want to replace roles.yesstring
role_idbodyID of the role that you want to assign to the composite role.yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the role that you want to update.yesstring
idbodyID of the user that you want to add or remove.yesstring
opbody

Type of operation that you want to perform.

Valid values:

  • add
  • remove
yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the role in which you want to replace users.yesstring
user_idbodyID of the user that you want to assign to the role.yesstring

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


NameLocated inDescriptionMandatorySchema
opbody

Type of operation that you want to perform.

Valid values:

  • add: Assigns the specified users to the role.
  • remove: Removes the specified users from the role.
  • replace: Replaces the existing users with the specified users.

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.

  1. Add operation is performed.
  2. Remove operation is performed.
  3. Replace operation is performed.
yesstring
user_ids
bodyComma-separated of user IDs to use for performing the operation.yesstring
role_idbody

ID of the role that you want to update.

yesstring

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 or 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, for example op. 

{
  "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."
}
 
Was this page helpful? Yes No Submitting... Thank you
Last modified by Priyanka Nanwani on Jul 28, 2021
development reference rest_api using_api authorization

Comments

User group endpoints in the REST API
Application endpoints in the REST API
© Copyright 2020-2021 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2021 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.