Modify Role

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.

User Privileges Required

You must be the creator of the role or have the Super User role.

Syntax

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

Request Body Parameters

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.

API Response

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.

Error Response

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.