创建角色

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 不能证明原创建已撤销。

共享请求/结果记录全部字段、权限和失败结果边界。

最后更新于