# 设置当前用户默认角色

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

```text
PUT https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/iam/me/default-role
```

## 调用前准备

从当前调用身份角色列表取得可选择的已直接绑定角色及 default_role_version，分别保存为 TARGET_ROLE_ID 和 DEFAULT_ROLE_VERSION；准备工作区凭据、jq 和本次 REQUEST_ID。目标不能仅是从继承关系中可达的角色。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X PUT "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/iam/me/default-role" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg role "$TARGET_ROLE_ID" --arg request "$REQUEST_ID" --argjson version "$DEFAULT_ROLE_VERSION" '{target_role_id:$role,expected_default_role_version:$version,request_id:$request}')"
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| target_role_id | string，必填 | 规范正整数角色 ID，须是当前用户可选的 active/ready 直接绑定。 |
| expected_default_role_version | integer | 当前默认角色版本，不小于 0；省略为 0，不表示跳过并发检查。 |
| request_id | string，必填 | 本次操作标识，相同内容确认使用原 ID。 |

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

## 返回结果

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "default_role_id": "7",
    "default_role_version": 3,
    "schema_version": "definition-example",
    "capability_version": "definition-example",
    "audit_event_id": "audit-example",
    "request_id": "default-example",
    "trace_id": "trace-example",
    "idempotent_replay": false
  }
}
```

:::::
:::::{tab-item} 字段说明

默认角色、回执和审计在同一事务保存。相同用户/工作区/request_id 与相同内容可重放，改变目标或输入版本复用编号冲突。重新读取当前角色上下文确认新默认值。它不为用户增加绑定，也不修改其他用户。

当前显式候选仍优先于默认值；更改默认角色不自动覆盖 SDK/CLI 已配置的工作区角色映射。

当前 Go/Python/CLI 未找到专用设置默认角色方法/命令；使用本页 HTTP，不虚构客户端方法。

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