Update a role¶

Update a specified role’s name and description. Only a role that remains editable can be updated.

HTTP
PATCH $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/iam/roles/{role_id}

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First select the role, confirm that it remains editable, and prepare the update using its current state in the list.

Request parameters¶

Input examples

Shell
curl -X PATCH "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"req-001","name":"Data analyst","description":"Responsible for viewing analytical data","expected_lifecycle_version":1}'

Parameter description

Path parameters

Parameter	Type	Required	Description
workspace_id	string	Yes	Target workspace ID.
role_id	string	Yes	Target role ID.

Request body

Parameter	Type	Required	Description
request_id	string	Yes	Request ID.
name	string	Yes	Role name.
description	string	No	Updated role description. Omit it to store an empty string.
expected_lifecycle_version	integer	Yes	Expected role lifecycle version. Must be greater than `0`.

Successful response¶

On success, returns the updated role summary and new lifecycle version. Replaying the same request ID with the same content does not apply the update again.

Response example

JSON
{"code":"OK","msg":"OK","data":{"role":{"workspace_id":"workspace-001","role_id":"role-001","role_name":"analyst","description":"Data analysis role","lifecycle_state":"active","lifecycle_version":4,"system_role":false},"idempotent_replay":false}}

Field details

Field	Type	Description
code	string	`OK` on success.
msg	string	`OK` on success.
data.role	object	Updated role summary.
data.role.lifecycle_version	integer	Updated role lifecycle version.
data.idempotent_replay	boolean	Whether this is an idempotent replay of the same request.

Error response¶

Response example

JSON
{"code":"ErrParamInvalid","msg":"请求参数无效","data":null}

Field details

Field	Type	Description
code	string	Error code.
msg	string	Error message.
data	null	—

Last updated on Sep 15, 2026