# Delete a role

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

Delete a specified role. A role cannot be deleted while it is referenced by user bindings, inheritance relationships, resource ownership, grants, or pending changes.

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

## Preparation before calling

First [select the role](list-roles.md#select-a-role), then [view its deletion impact](get-role-delete-impact.md#confirm-deletion-impact) to confirm there are no blockers. Before deleting, confirm again that the role is no longer in use.

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 DELETE "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/iam/roles/$ROLE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-001",
    "reason_code": "role_no_longer_needed",
    "expected_lifecycle_version": 1
  }'
```

:::::
:::::{tab-item} Parameter description

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| workspace_id | string | Yes | Target workspace ID. |
| role_id | string | Yes | Target role ID. |

### Request body

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| request_id | string | Yes | Request ID. |
| reason_code | string | Yes | Deletion reason code. |
| expected_lifecycle_version | integer | Yes | Expected role lifecycle version. Must be greater than `0`. |

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

## Successful response

On success, the role has passed final reference checks and has been deleted; the response returns the role facts after deletion. Replaying the same request ID with the same content does not delete it again.

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "role": {
      "workspace_id": "workspace-001",
      "role_id": "role-001",
      "role_name": "analyst",
      "lifecycle_state": "deleted",
      "lifecycle_version": 4,
      "system_role": false
    },
    "idempotent_replay": false
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| code | string | `OK` on success. |
| msg | string | `OK` on success. |
| data.role | object | Role facts after deletion. |
| data.role.role_id | string | Deleted role ID. |
| data.role.lifecycle_state | string | Lifecycle state after deletion. |
| data.role.lifecycle_version | integer | Lifecycle version after deletion. |
| 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 | — |

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