Migrating a Standalone Resource Group to an Organization

This guide walks you through migrating an existing, standalone resource group into your new Organization.

Because unified governance requires all resource group members to also be organization members, migrations can sometimes hit a roadblock if the resource group contains external users. This tutorial demonstrates how to handle such a conflict using the API.

Scenario Overview

You are an Organization Admin. You have a legacy resource group (resourceGroupId: 42) that you want to move into your organization. However, two users in this resource group ([email protected] and [email protected]) are not yet part of your organization. We want to keep Alice, but we are fine with Bob being removed from the resource group during the move.

Step 1: Retrieve your Organization ID

Before we can migrate the resource group, we need to know the target organizationId. We fetch a list of all organizations we belong to.

• Endpoint: GET /organizations
• Action: Find your target organization in the response array and copy its id (e.g., 123e4567-e89b-12d3-a456-426614174000).

Step 2: Attempt the Migration (and fail)

We attempt to migrate the resource group. Because we want to be safe, we omit the force flag (which defaults to false).

• Endpoint: POST /resource-groups/42/migrate

• Payload:

  {
    "organizationId": "123e4567-e89b-12d3-a456-426614174000"
  }

• Result: The API rejects the request because Alice and Bob are not in the organization. You will receive a 400 Bad Request with the following error detail:

  Cannot migrate team to organization because the following team members are not members of the new organization: [email protected], [email protected]. Either add the members to the organization before migrating, or use the force option to remove them from the team and proceed with the migration.

Step 3: Add the Required Member

We decide we want Alice to remain in the resource group, so we must first invite her to the umbrella organization.

• Endpoint: POST /organizations/123e4567-e89b-12d3-a456-426614174000/members
• Payload:

  {
    "email": "[email protected]",
    "role": "member"
  }

• Result: Alice is now officially part of the organization.

Step 4: Force the Migration

We do not want to add Bob to our organization. We accept that he will lose access to the resource group once it is migrated. We run the migration endpoint again, this time explicitly setting force: true.

• Endpoint: POST /resource-groups/42/migrate
• Payload:

  {
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "force": true
  }

• Result: Success! HTTP 200 OK. The resource group is moved into the organization. Bob is automatically removed from the resource group, while Alice remains a resource group member.

Step 5: Verify the Migration

Finally, we check our organization's resource group list to ensure the legacy resource group is now properly grouped under our governance structure.

• Endpoint: GET /organizations/123e4567-e89b-12d3-a456-426614174000/resource-groups
• Result: The response array will now include the newly migrated resource group.