Delete Roles and Resolve Dependencies

Before deleting a workspace role, inspect its deletion impact, member bindings, and owned objects, then transfer object ownership and update member bindings before submitting the deletion request.

Task flow

Workspace IAM handle
         │
         ▼
1. Read deletion impact, member bindings, and owned objects for the role
         │
         ▼
2. Transfer object ownership and update member role bindings
         │
         ▼
3. Re-verify zero blockers ──▶ Submit deletion request and confirm role state

Prerequisites

  1. Complete the endpoint, personal access token, and workspace setup in Use the SDK.

  2. Ensure the current identity holds role management and object ownership transfer permissions in the target workspace.

  3. Determine the role ID to delete and the recipient role ID that will take over owned objects; list the workspace role directory as shown in Manage Roles and Object Permissions.

  4. Prepare unique request IDs for ownership transfers and role deletion, and retain them to verify status if a network timeout occurs.

1. Inspect impact and dependencies

Read the current lifecycle version of the target role, then query its deletion impact, bound members, and owned objects. Both the member list and the owned-object list return pagination cursors for reading subsequent pages when needed.

import os
import uuid

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
iam = client.iam(os.environ["WORKSPACE_ID"])
role_id = os.environ["ROLE_ID"]

view = iam.role_permission_view(role_id)
impact = iam.role_delete_impact(role_id, view.expected_role_lifecycle_version)
members = iam.role_members(role_id)
owned = iam.role_delete_ownerships(role_id)

print("Blocked:", impact.blocked)
print("Bindings:", impact.direct_binding_count, "Defaults:", impact.default_role_count)
print("Owned objects:", impact.active_ownership_count, "Pending ops:", impact.pending_operation_count)
for member in members.members:
    print("member:", member.user_id, "default_role:", member.default_role)
for item in owned.items:
    print("owned:", item.resource_type, item.resource_id, item.display_name, item.ownership_version)
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	iam := client.IAM(os.Getenv("WORKSPACE_ID"))
	roleID := os.Getenv("ROLE_ID")

	view, err := iam.RolePermissionView(ctx, roleID)
	if err != nil {
		panic(err)
	}
	impact, err := iam.RoleDeleteImpact(ctx, roleID, view.GetExpectedRoleLifecycleVersion())
	if err != nil {
		panic(err)
	}
	fmt.Println("Blocked:", impact.GetBlocked())
	fmt.Println("Bindings:", impact.GetDirectBindingCount(), "Defaults:", impact.GetDefaultRoleCount())
	fmt.Println("Owned objects:", impact.GetActiveOwnershipCount(), "Pending ops:", impact.GetPendingOperationCount())

	members, err := iam.RoleMembers(ctx, roleID)
	if err != nil {
		panic(err)
	}
	for _, member := range members.GetMembers() {
		fmt.Println("member:", member.GetUserId(), "default_role:", member.GetDefaultRole())
	}

	owned, err := iam.RoleDeleteOwnerships(ctx, roleID)
	if err != nil {
		panic(err)
	}
	for _, item := range owned.GetItems() {
		fmt.Println("owned:", item.GetResourceType(), item.GetResourceId(), item.GetDisplayName(), item.GetOwnershipVersion())
	}
	_ = time.Now
}

2. Resolve member and ownership dependencies

When the deletion preflight reports blockers, clear each dependency category before deleting the role:

  • Transfer object ownership: For each item in the ownership list, pass its resource type, resource ID, expected ownership version, and recipient role ID to transfer ownership.

  • Update member role bindings: If any members still hold the target role or use it as their default role, read their role binding versions and reassign them to active roles.

  • Review inheritance impact: Deleting a role removes its inheritance edges; check child roles that inherit permissions through it via Configure Role Inheritance.

The following continuation transfers each owned object on the current page to the recipient role:

recipient_role_id = os.environ["RECIPIENT_ROLE_ID"]
for item in owned.items:
    transferred = iam.transfer_object_ownership(
        item.resource_type,
        item.resource_id,
        sdk.IAMObjectOwnershipTransferRequest(
            target_role_id=recipient_role_id,
            expected_ownership_version=item.ownership_version,
            request_id=str(uuid.uuid4()),
        ),
    )
    print("transferred:", item.resource_type, item.resource_id, "->", transferred.owner.role_id)
recipientRoleID := os.Getenv("RECIPIENT_ROLE_ID")
for index, item := range owned.GetItems() {
	transferred, err := iam.TransferObjectOwnership(
		ctx,
		item.GetResourceType(),
		item.GetResourceId(),
		&sdk.IAMObjectOwnershipTransferRequest{
			TargetRoleId:             recipientRoleID,
			ExpectedOwnershipVersion: item.GetOwnershipVersion(),
			RequestId:                fmt.Sprintf("owner-transfer-%d-%d", time.Now().UnixNano(), index),
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("transferred:", item.GetResourceType(), item.GetResourceId(), "->", transferred.GetOwner().GetRoleId())
}

3. Submit role deletion

After clearing member bindings and ownership dependencies, re-read the role’s lifecycle version and deletion impact to verify that blocked is false, then submit the deletion request.

view = iam.role_permission_view(role_id)
impact = iam.role_delete_impact(role_id, view.expected_role_lifecycle_version)
if impact.blocked:
    raise SystemExit("Resolve remaining blockers before deleting the role")

result = iam.delete_role(
    role_id,
    sdk.IAMRoleDeleteRequest(
        reason_code="retired",
        expected_lifecycle_version=view.expected_role_lifecycle_version,
        request_id=os.environ["DELETE_REQUEST_ID"],
    ),
)
print("Deleted role:", result.role.role_id, "state:", result.role.lifecycle_state)
view, err = iam.RolePermissionView(ctx, roleID)
if err != nil {
	panic(err)
}
impact, err = iam.RoleDeleteImpact(ctx, roleID, view.GetExpectedRoleLifecycleVersion())
if err != nil {
	panic(err)
}
if impact.GetBlocked() {
	panic("Resolve remaining blockers before deleting the role")
}

result, err := iam.DeleteRole(ctx, roleID, &sdk.IAMRoleDeleteRequest{
	ReasonCode:               "retired",
	ExpectedLifecycleVersion: view.GetExpectedRoleLifecycleVersion(),
	RequestId:                os.Getenv("DELETE_REQUEST_ID"),
})
if err != nil {
	panic(err)
}
fmt.Println("Deleted role:", result.GetRole().GetRoleId(), "state:", result.GetRole().GetLifecycleState())

If a network timeout leaves the deletion outcome uncertain, reuse the same DELETE_REQUEST_ID or inspect the role directory and transferred objects before issuing any new request.

Next steps

Last updated on