Delete a role¶

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

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

Preparation before calling¶

First select the role, then view its 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.

Request parameters¶

Input example

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
  }'

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.

Response example

{
  "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
  }
}

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¶

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