创建角色¶
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/iam/roles
调用前准备¶
准备工作区凭据、jq 和权限定义的 SCHEMA_VERSION;调用方当前有效角色须有 role.create。为创建生成不超过 64 UTF-8 字节、不含空白/控制字符的 REQUEST_ID。用户选择的初始应用权限或数据权限至少有一项有效。示例授予查看全部工作流。
请求¶
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:[]}')"
字段 |
类型 |
说明 |
|---|---|---|
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[] |
初始数据授权,完整字段见共享对象。 |
返回结果¶
{
"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"
}
}
成功为 HTTP 201,只有 ready 是成功提交点,不应通过一个成功空壳角色再追加初始权限。过滤既有历史 model_runtime.invoke 后仍无有效权限时为 422 ErrIAMRolePermissionRequired。名称重复为 409 ErrIAMRoleNameExists。
同 ID/相同内容已成功时返回历史回执;改变内容冲突。原请求仍未确认时可能返回 409 ErrIAMRoleWriteResultUnknown,不重新执行创建。已确认清理为 ErrIAMRoleWriteRolledBack;已停止但不能确认完整恢复为 ErrIAMRoleWriteFailed。无响应或前置 403 不能证明原创建已撤销。
共享请求/结果记录全部字段、权限和失败结果边界。