# Update user role bindings

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## Preparation before calling

First [select the user](list-users.md#select-a-user), then [view the user's role bindings](get-user-role-bindings.md#confirm-current-role-bindings) to confirm the current binding state. Next, [select roles](../roles/list-roles.md#select-a-role) to determine the new role assignment and default role.

Prepare a [personal access token](../../../../../guides/genesis/api-keys.md#manage-api-keys) and [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id) with the required permissions for the target workspace.

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Input example

```bash
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
  }'
```

:::::
:::::{tab-item} 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.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "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"
  }
}
```

:::::
:::::{tab-item} 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

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Field details

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

:::::
::::::
:::::::