Add role inheritance¶

Add a direct parent role to a specified role. The relationship cannot create an inheritance cycle.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/iam/roles/{role_id}/parents

Preparation before calling¶

First select the roles to identify the child and parent roles. Then view role inheritance to confirm that they do not already have a direct inheritance relationship. If necessary, view the role inheritance graph to prevent a cycle.

Prepare a personal access token with the required permission in the target workspace and the target workspace ID.

Request parameters¶

Input example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID/parents" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"parent_role_id\": \"$PARENT_ROLE_ID\",
    \"expected_child_lifecycle_version\": 1,
    \"expected_parent_lifecycle_version\": 1,
    \"expected_role_graph_version\": \"graph-v1\",
    \"request_id\": \"req-001\"
  }"

Parameter description

Path parameters

Parameter	Type	Required	Description
workspace_id	string	Yes	Target workspace ID.
role_id	string	Yes	Child role ID that receives the inheritance relationship.

Request body

Parameter	Type	Required	Description
parent_role_id	string	Yes	Parent role ID.
expected_child_lifecycle_version	integer	Yes	Current lifecycle version of the child role. Must be greater than `0`.
expected_parent_lifecycle_version	integer	Yes	Current lifecycle version of the parent role. Must be greater than `0`.
expected_role_graph_version	string	Yes	Current role graph version.
request_id	string	Yes	Caller-generated idempotency request ID.

Successful response¶

On success, the inheritance relationship has been added and the API returns the new role graph version. Replaying the same request ID with the same content does not add the relationship again.

Response example

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "child_role_id": "role-001",
    "parent_role_id": "role-parent",
    "role_graph_version": "graph-v2",
    "idempotent_replay": false
  }
}

Field details

Field	Type	Description
code	string	`OK` on success.
msg	string	`OK` on success.
data.child_role_id	string	Child role ID.
data.parent_role_id	string	Parent role ID that was added.
data.role_graph_version	string	Updated role graph version.
data.idempotent_replay	boolean	Whether this is an idempotent replay of the same request.

Error response¶

Response example

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

Field details

Field	Type	Description
code	string	Error code.
msg	string	Error message.
data	null	—

Last updated on Sep 3, 2026