Update user role bindings¶

Update the roles and default role of a specified user. The submitted role assignment replaces the user’s current role bindings.

PUT https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/iam/users/{user_id}/role-bindings

Preparation before calling¶

First select the user, then view the user’s role bindings to confirm the current binding state. Next, select roles to determine the new role assignment and default role.

Prepare a personal access token and target workspace ID with the required permissions for the target workspace.

Request parameters¶

Input example

curl -X PUT "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/users/$USER_ID/role-bindings" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_role_ids": ["role-001"],
    "default_role_id": "role-001",
    "expected_binding_version": 0,
    "expected_default_role_version": 0,
    "request_id": "req-001",
    "clear_default_role": false
  }'

Parameter description

Path parameters

Parameter	Type	Required	Description
`workspace_id`	string	Yes	Target workspace ID.
`user_id`	string	Yes	ID of the user whose role bindings you want to update.

Request body

Parameter	Type	Required	Description
`assigned_role_ids`	string (array)	Yes	Complete list of direct role IDs after the update.
`default_role_id`	string	No	Default role ID.
`expected_binding_version`	integer	No	Current role-binding version; it cannot be less than 0.
`expected_default_role_version`	integer	No	Current default-role version; it cannot be less than 0.
`request_id`	string	Yes	Idempotency request ID generated by the caller.
`clear_default_role`	boolean	No	Whether to clear the default role.

This endpoint fully replaces the user’s direct role bindings. The request is rejected when default_role_id is empty and clear_default_role is false. To clear the default role, set clear_default_role to true; to retain or change it, submit the corresponding default_role_id.

Successful response¶

On success, direct role bindings and the default role have been updated in the same transaction, and the response returns the new versions. Replaying the same request ID with identical content does not perform the update again.

Response example

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "user_id": "user-001",
    "assigned_role_ids": ["role-001"],
    "default_role_id": "role-001",
    "binding_version": 4,
    "default_role_version": 3,
    "audit_event_id": "audit-001",
    "idempotent_replay": false,
    "request_id": "req-001",
    "trace_id": "trace-001"
  }
}

Field details

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.user_id`	string	User ID whose bindings were updated.
`data.assigned_role_ids`	string (array)	Updated direct role IDs.
`data.default_role_id`	string	Updated default role ID; empty when cleared.
`data.binding_version`	integer	Updated role-binding version.
`data.default_role_version`	integer	Updated default-role version.
`data.audit_event_id`	string	Audit event ID for this change.
`data.idempotent_replay`	boolean	Whether this is an idempotent replay of the same request.
`data.request_id`	string	Request correlation ID.
`data.trace_id`	string	Trace ID.

Error response¶

Response example

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

Field details

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

Last updated on Sep 3, 2026