# 创建角色

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

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

## 调用前准备

准备工作区凭据、jq 和权限定义的 SCHEMA_VERSION；调用方当前有效角色须有 role.create。为创建生成不超过 64 UTF-8 字节、不含空白/控制字符的 REQUEST_ID。用户选择的初始应用权限或数据权限至少有一项有效。示例授予查看全部工作流。

## 请求

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/iam/roles" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg schema "$SCHEMA_VERSION" --arg request "$REQUEST_ID" '{name:"analyst",description:"Workflow readers",schema_version:$schema,request_id:$request,statements:[{action_id:"workflow.read",resource_type:"workflow",scope_mode:"all"}],data_privilege_mutations:[]}')"
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| name | string，必填 | 1–255 UTF-8 字节，不含空白/控制字符，不使用系统保留名称。 |
| description | string，可选 | 最多 4096 UTF-8 字节，不含 NUL；省略/null 为空。 |
| schema_version | string，必填 | 当前权限定义指纹；由服务端按当前定义验证意图。 |
| request_id | string，必填 | 同一次创建及确认沿用原 ID 和相同内容。 |
| statements | object[] | 初始应用策略，完整字段见共享对象。 |
| data_privilege_mutations | object[] | 初始数据授权，完整字段见共享对象。 |

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

## 返回结果

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "role_id": "8",
    "role_version": 1,
    "policy_version": 2,
    "data_privilege_version": 0,
    "session_invalidation_status": "not_applicable",
    "idempotent_replay": false,
    "provisioning_state": "ready",
    "provisioning_version": 2,
    "provisioning_error_code": "",
    "request_id": "create-example",
    "trace_id": "trace-example"
  }
}
```

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

成功为 HTTP 201，只有 ready 是成功提交点，不应通过一个成功空壳角色再追加初始权限。过滤既有历史 model_runtime.invoke 后仍无有效权限时为 422 ErrIAMRolePermissionRequired。名称重复为 409 ErrIAMRoleNameExists。

同 ID/相同内容已成功时返回历史回执；改变内容冲突。原请求仍未确认时可能返回 409 ErrIAMRoleWriteResultUnknown，不重新执行创建。已确认清理为 ErrIAMRoleWriteRolledBack；已停止但不能确认完整恢复为 ErrIAMRoleWriteFailed。无响应或前置 403 不能证明原创建已撤销。

[共享请求/结果](iam-write-objects.md)记录全部字段、权限和失败结果边界。

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