This API helps you modify an existing role. The existing privileges of the role will be overwritten by the new privileges provided in the request XML.
Note that you cannot modify the system roles. For more details on system roles, see Appendix.
You must be the creator of the role or have the Super User role.
The syntax for calling this method is:
PUT <Base_Url>/role
/{roleId}
A sample API call is as follows:
PUT https://123.123.123.123/vCenter-CB/api/role
/15
The request XML for this API includes the following parameters.
XPath |
Type |
Min Occurs |
Max Occurs |
Description |
---|---|---|---|---|
Roles/Role |
|
1 |
1 |
Represents the Role element. |
Roles/Role/Name |
xs:string |
1 |
1 |
Name of the role. |
Roles/Role/Description |
xs:string |
0 |
1 |
An optional description of the role. |
Roles/Role/Privileges/Privilege |
|
|
|
Represents the Privileges element for a role. |
Roles/Role/Privileges/Privilege/@id |
xs:int |
1 |
unbounded |
Unique ID of the privilege assigned to the role. |
A sample request XML is provided here.
If the operation is successful, the API gets an XML response with the following details.
XPath |
Type |
Min Occurs |
Max Occurs |
Description |
---|---|---|---|---|
Roles/Role |
|
1 |
1 |
This is the Role element |
Roles/Role/@id |
xs:int |
1 |
1 |
ID of the role. |
Roles/Role/Name |
xs:string |
1 |
1 |
Name for the user role. |
Roles/Role/Description |
xs:string |
1 |
1 |
An optional description for the user role. |
Roles/Role/Custom |
xs:boolean |
|
|
Indicates whether the new role is a custom role. |
Roles/Role/Privileges/Privilege |
|
1 |
unbounded |
This is the Privilege element |
Roles/Role/Privileges/Privilege/@id |
xs:int |
1 |
1 |
The unique ID of the privilege the user role is assigned. |
Privileges/Privilege |
|
|
|
Represents the Privileges element. |
Privileges/Privilege/@id |
xs:int |
1 |
1 |
ID of the privilege. |
Privileges/Privilege/Name |
xs:string |
1 |
1 |
Name of the privilege. |
Privileges/Privilege/Description |
xs:string |
1 |
1 |
Description of the privilege. |
Privileges/Privilege/ResourceType/@id |
xs:int |
1 |
1 |
ID of the resource type |
A sample response is provided here.
The following table explains the error codes displayed by the API.
Error code |
Description |
VCENTER_COMMON_ERR_INSUFFICIENT_PERMISSION |
User does not have sufficient permissions for performing this operation. |
VCENTER_COMMON_ERR_USER_NOT_AUTHENTICATED |
User is not authenticated to perform this operation |
VCENTER_COMMON_ERR_INVALID_INPUT_XML |
The given request XML is not in the desired format. |
VCB_ERR_INVALID_ROLE_ID |
No role exists with the given role ID. |
VCB_ERR_SYSTEM_ROLE_ALTER |
The role ID that you have specified is of a system role. |
VCB_ERR_INVALID_ROLE_NAME |
Role name is longer than 255 characters or invalid. |
VCB_ERR_INVALID_ROLE_DESCRIPTION |
Description is longer than 512 characters. |
VCB_ERR_ROLE_NAME_EXISTS |
A role with the same name exists |
VCB_ERR_INVALID_PRIVILEGE_ID |
No privilege exists with the given privilege ID. |
VCB_ERR_PRIVILEGES_MISSING |
You cannot create a role without privileges. |