# 查询角色成员

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

```text
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/iam/roles/{role_id}/members
```

## 调用前准备

先读取角色列表取得规范正整数角色 ID；准备有工作区 role.read 的当前角色、工作区凭据。返回的是直接绑定用户，不能把显示名或邮箱当 user_id。

## 请求

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

```bash
curl -X GET "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/members" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --get \
  --data-urlencode "limit=1"
```

```bash
curl -X GET "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/members" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --get \
  --data-urlencode "limit=1" \
  --data-urlencode "cursor=$NEXT_CURSOR"
```

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

返回非空 next_cursor 时将其原样保存为 NEXT_CURSOR，再读取：



| 字段 | 类型 | 说明 |
| --- | --- | --- |
| limit | integer | 默认 50，1–200；空值使用默认值。 |
| cursor | string | 上一页的 next_cursor；首次省略。 |

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

## 返回结果

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "role_id": "8",
    "members": [
      {
        "user_id": "canonical-user-example",
        "display_name": "Example user",
        "email": "",
        "default_role": false,
        "default_role_version": 2,
        "binding_created_at": 1794390000
      }
    ],
    "next_cursor": "canonical-user-example",
    "request_id": "request-example",
    "trace_id": "trace-example"
  }
}
```

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

结果按 canonical user_id 升序，next_cursor 为空时结束。目录资料按当前页批量补充；确认资料缺失保留用户及空展示值，目录读取失败返回依赖错误，不改成空列表。binding_created_at 为 Unix 秒，default_role_version 是该用户默认角色版本。

空列表不能单独证明角色存在；当前所读服务/DAO 未先按目标角色查存在性。列表不汇总继承成员，也不解绑用户。用于删除时还需另外读取当前删除影响，读取空成员页不代表可删除。

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