# Add role inheritance

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

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

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

## Preparation before calling

First [select the roles](list-roles.md#select-a-role) to identify the child and parent roles. Then [view role inheritance](list-role-inheritance.md#confirm-inheritance-relationships) to confirm that they do not already have a direct inheritance relationship. If necessary, [view the role inheritance graph](get-role-inheritance-graph.md#confirm-the-inheritance-graph) to prevent a cycle.

Prepare a personal access token with the required permission in the target workspace and the [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-a-workspace-id).

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Input example

```bash
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\"
  }"
```

:::::
:::::{tab-item} 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.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} 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

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Field details

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

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