Configure a multitenant organization using PowerShell or Microsoft Graph API

This article describes the key steps to configure a multitenant organization using Microsoft Graph PowerShell or Microsoft Graph API. This article uses an example owner tenant named Cairo and two member tenants named Berlin and Athens.

If you instead want to use the Microsoft 365 admin center to configure a multitenant organization, see Set up a multitenant org in Microsoft 365 and Join or leave a multitenant organization in Microsoft 365. To learn how to configure Microsoft Teams for your multitenant organization, see The new Microsoft Teams desktop client.

Prerequisites

Owner tenant

• For license information, see License requirements.
• Security Administrator role to configure cross-tenant access settings and templates for the multitenant organization.
• Global Administrator role to consent to required permissions.

Member tenant

• For license information, see License requirements.
• Security Administrator role to configure cross-tenant access settings and templates for the multitenant organization.
• Global Administrator role to consent to required permissions.

Step 1: Sign in to the owner tenant

Owner tenant

PowerShell

1. Start PowerShell.

2. If necessary, install the Microsoft Graph PowerShell SDK.

3. Get the tenant ID of the owner and member tenants and initialize variables.

   $OwnerTenantId = "<OwnerTenantId>"
   $MemberTenantIdB = "<MemberTenantIdB>"
   $MemberTenantIdA = "<MemberTenantIdA>"
   

4. Use the Connect-MgGraph command to sign in to the owner tenant and consent to the following required permissions.

   • MultiTenantOrganization.ReadWrite.All
   • Policy.Read.All
   • Policy.ReadWrite.CrossTenantAccess
   • Application.ReadWrite.All
   • Directory.ReadWrite.All

   Connect-MgGraph -TenantId $OwnerTenantId -Scopes "MultiTenantOrganization.ReadWrite.All","Policy.Read.All","Policy.ReadWrite.CrossTenantAccess","Application.ReadWrite.All","Directory.ReadWrite.All"
   

Microsoft Graph

These steps describe how to use Microsoft Graph Explorer, but you can also use another REST API client.

1. Start Microsoft Graph Explorer tool.

2. Sign in to the owner tenant.

3. Select your profile and then select Consent to permissions.

4. Consent to the following required permissions.

   • MultiTenantOrganization.ReadWrite.All
   • Policy.Read.All
   • Policy.ReadWrite.CrossTenantAccess
   • Application.ReadWrite.All
   • Directory.ReadWrite.All

Step 2: Create a multitenant organization

Owner tenant

PowerShell

1. In the owner tenant, use the Update-MgBetaTenantRelationshipMultiTenantOrganization command to create your multitenant organization. This operation can take a few minutes.

   Update-MgBetaTenantRelationshipMultiTenantOrganization -DisplayName "Cairo"
   

2. Use the Get-MgBetaTenantRelationshipMultiTenantOrganization command to check that the operation has completed before proceeding.

   Get-MgBetaTenantRelationshipMultiTenantOrganization | Format-List
   

   CreatedDateTime      : 1/8/2024 7:47:45 PM
   Description          :
   DisplayName          : Cairo
   Id                   : <MtoIdC>
   JoinRequest          : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationJoinRequestRecord
   State                : active
   Tenants              :
   AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/$entity]}
   

Microsoft Graph

1. In the owner tenant, use the Create multiTenantOrganization API to create your multitenant organization. This operation can take a few minutes.

   Request

   PUT https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization
   {
       "displayName": "Cairo"
   }
   

2. Use the Get multiTenantOrganization API to check that the operation has completed before proceeding.

   Request

   GET https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization
   

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/$entity",
       "id": "{mtoId}",
       "createdDateTime": "2023-11-20T20:38:20Z",
       "state": "active",
       "displayName": "Cairo",
       "description": null
   }
   

Step 3: Add tenants

Owner tenant

PowerShell

1. In the owner tenant, use the New-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to add tenants to your multitenant organization.

   New-MgBetaTenantRelationshipMultiTenantOrganizationTenant -TenantID $MemberTenantIdB -DisplayName "Berlin" | Format-List
   

   New-MgBetaTenantRelationshipMultiTenantOrganizationTenant -TenantID $MemberTenantIdA -DisplayName "Athens" | Format-List
   

2. Use the Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to verify that the operation has completed before proceeding.

   Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant | Format-List
   

   AddedByTenantId      : <OwnerTenantId>
   AddedDateTime        : 1/8/2024 7:47:45 PM
   DeletedDateTime      :
   DisplayName          : Cairo
   Id                   : <MtoIdC>
   JoinedDateTime       :
   Role                 : owner
   State                : active
   TenantId             : <OwnerTenantId>
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationMemberTransitionDetails
   AdditionalProperties : {[multiTenantOrgLabelType, none]}
   
   AddedByTenantId      : <OwnerTenantId>
   AddedDateTime        : 1/8/2024 8:05:25 PM
   DeletedDateTime      :
   DisplayName          : Berlin
   Id                   : <MtoIdB>
   JoinedDateTime       :
   Role                 : member
   State                : pending
   TenantId             : <MemberTenantIdB>
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationMemberTransitionDetails
   AdditionalProperties : {[multiTenantOrgLabelType, none]}
   
   AddedByTenantId      : <OwnerTenantId>
   AddedDateTime        : 1/8/2024 8:08:47 PM
   DeletedDateTime      :
   DisplayName          : Athens
   Id                   : <MtoIdA>
   JoinedDateTime       :
   Role                 : member
   State                : pending
   TenantId             : <MemberTenantIdA>
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationMemberTransitionDetails
   AdditionalProperties : {[multiTenantOrgLabelType, none]}
   

Microsoft Graph

1. In the owner tenant, use the Add multiTenantOrganizationMember API to add tenants to your multitenant organization.

   Request

   POST https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants
   {
       "tenantId": "{memberTenantIdB}",
       "displayName": "Berlin"
   }
   

   Request

   POST https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants
   {
       "tenantId": "{memberTenantIdA}",
       "displayName": "Athens"
   }
   

2. Use the List multiTenantOrganizationMembers API to verify that the operation has completed before proceeding.

   Request

   GET https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants
   

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/tenants"
       "value": [
           {
               "tenantId": "{ownerTenantId}",
               "displayName": "Cairo",
               "addedDateTime": "2023-11-20T20:38:20Z",
               "joinedDateTime": null,
               "addedByTenantId": "{ownerTenantId}",
               "role": "owner",
               "state": "active",
               "transitionDetails": null
           },
           {
               "tenantId": "{memberTenantIdB}",
               "displayName": "Berlin",
               "addedDateTime": "2023-11-20T21:22:35Z",
               "joinedDateTime": null,
               "addedByTenantId": "{ownerTenantId}",
               "role": "member",
               "state": "pending",
               "transitionDetails": {
                   "desiredState": "active",
                   "desiredRole": "member",
                   "status": "notStarted",
                   "details": null
               }
           },
           {
               "tenantId": "{memberTenantIdA}",
               "displayName": "Athens",
               "addedDateTime": "2023-11-20T21:24:59Z",
               "joinedDateTime": null,
               "addedByTenantId": "{ownerTenantId}",
               "role": "member",
               "state": "pending",
               "transitionDetails": {
                   "desiredState": "active",
                   "desiredRole": "member",
                   "status": "notStarted",
                   "details": null
               }
           }
       ]
   }
   

Step 4: (Optional) Change the role of a tenant

Owner tenant

By default, tenants added to the multitenant organization are member tenants. Optionally, you can change them to owner tenants, which allow them to add other tenants to the multitenant organization. You can also change an owner tenant to a member tenant.

PowerShell

1. In the owner tenant, use the Update-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to change a member tenant to an owner tenant.

   Update-MgBetaTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId $MemberTenantIdB -Role "Owner" | Format-List
   

2. Use the Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to verify the change.

   Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId $MemberTenantIdB | Format-List
   

   AddedByTenantId      : <OwnerTenantId>
   AddedDateTime        : 1/8/2024 8:05:25 PM
   DeletedDateTime      :
   DisplayName          : Berlin
   Id                   : <MtoIdB>
   JoinedDateTime       :
   Role                 : owner
   State                : pending
   TenantId             : <MemberTenantIdB>
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationMemberTransitionDetails
   AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/tenants/$entity],
                          [multiTenantOrgLabelType, none]}
   

Microsoft Graph

1. In the owner tenant, use the Update multiTenantOrganizationMember API to change a member tenant to an owner tenant.

   Request

   PATCH https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{memberTenantIdB}
   {
       "role": "owner"
   }
   

2. Use the Get multiTenantOrganizationMember API to verify the change.

   Request

   GET https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{memberTenantIdB}
   

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/tenants/$entity",
       "tenantId": "{memberTenantIdB}",
       "displayName": "Berlin",
       "addedDateTime": "2023-11-20T21:22:35Z",
       "joinedDateTime": null,
       "addedByTenantId": "{ownerTenantId}",
       "role": "member",
       "state": "pending",
       "transitionDetails": {
           "desiredState": "active",
           "desiredRole": "owner",
           "status": "notStarted",
           "details": null
       } 
   }
   

3. Use the Update multiTenantOrganizationMember API to change an owner tenant to a member tenant.

   Request

   PATCH https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{memberTenantIdB}
   {
       "role": "member"
   }
   

Step 5: (Optional) Remove a member tenant

Owner tenant

You can remove any member tenant, including your own. You can't remove owner tenants. Also, you can't remove the original creator tenant, even if it has been changed from owner to member.

PowerShell

1. In the owner tenant, use the Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to remove any member tenant. This operation takes a few minutes.

   Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId <MemberTenantIdD>
   

2. Use the Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to verify the change.

   Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId <MemberTenantIdD>
   

   After the remove command completes, the output is similar to the following. This is an expected error message. It indicates that the tenant has been removed from the multitenant organization.

   Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant_Get: Unable to read the company information from the directory.
   
   Status: 404 (NotFound)
   ErrorCode: Directory_ObjectNotFound
   Date: 2024-01-08T20:35:11
   
   ...
   

Microsoft Graph

1. In the owner tenant, use the Remove multiTenantOrganizationMember API to remove any member tenant. This operation takes a few minutes.

   Request

   DELETE https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{memberTenantIdD}
   

2. Use the Get multiTenantOrganizationMember API to verify the change.

   Request

   GET https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{memberTenantIdD}
   

   If you check immediately after calling the remove API, it will show a response similar to the following.

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/tenants/$entity",
       "tenantId": "{memberTenantIdD}",
       "displayName": "Denver",
       "addedDateTime": "2023-11-20T20:56:05Z",
       "joinedDateTime": null,
       "addedByTenantId": "{ownerTenantId}",
       "role": "member",
       "state": "pending",
       "transitionDetails": {
           "desiredState": "removed",
           "desiredRole": "member",
           "status": "notStarted",
           "details": null
       }
   }
   

   After the remove operation completes, the response is similar to the following. This is an expected error message. It indicates that the tenant has been removed from the multitenant organization.

   Response

   {
       "error": {
           "code": "Directory_ObjectNotFound",
           "message": "Unable to read the company information from the directory.",
           "innerError": {
               "date": "2023-11-20T21:09:53",
               "request-id": "75216961-c21d-49ed-8c1f-2cfe51f920f1",
               "client-request-id": "30129b19-51e8-41ed-8ba0-1501bac03802"
           }
       }
   }
   

Step 6: Sign in to a member tenant

Member tenant

The Cairo tenant created a multitenant organization and added the Berlin and Athens tenants. In these steps, you sign in to the Berlin tenant and join the multitenant organization created by Cairo.

PowerShell

1. Start PowerShell.

2. Use the Connect-MgGraph command to sign in to the member tenant and consent to the following required permissions.

   • MultiTenantOrganization.ReadWrite.All
   • Policy.Read.All
   • Policy.ReadWrite.CrossTenantAccess
   • Application.ReadWrite.All
   • Directory.ReadWrite.All

   Connect-MgGraph -TenantId $MemberTenantIdB -Scopes "MultiTenantOrganization.ReadWrite.All","Policy.Read.All","Policy.ReadWrite.CrossTenantAccess","Application.ReadWrite.All","Directory.ReadWrite.All"
   

Microsoft Graph

1. Start Microsoft Graph Explorer tool.

2. Sign in to the member tenant.

3. Select your profile and then select Consent to permissions.

4. Consent to the following required permissions.

   • MultiTenantOrganization.ReadWrite.All
   • Policy.Read.All
   • Policy.ReadWrite.CrossTenantAccess
   • Application.ReadWrite.All
   • Directory.ReadWrite.All

Step 7: Join the multitenant organization

Member tenant

PowerShell

1. In the member tenant, use the Update-MgBetaTenantRelationshipMultiTenantOrganizationJoinRequest command to join the multitenant organization.

   Update-MgBetaTenantRelationshipMultiTenantOrganizationJoinRequest -AddedByTenantId $OwnerTenantId | Format-List
   

2. Use the Get-MgBetaTenantRelationshipMultiTenantOrganizationJoinRequest command to verify the join.

   Get-MgBetaTenantRelationshipMultiTenantOrganizationJoinRequest | Format-List
   

   AddedByTenantId      : <OwnerTenantId>
   Id                   : <MtoJoinRequestIdB>
   MemberState          : active
   Role                 : member
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationJoinRequestTransitionDetails
   AdditionalProperties : {[@odata.context, https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/joinRequest/$entity]}
   

3. Use the Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to check the multitenant organization itself. It should reflect the join operation.

   Get-MgBetaTenantRelationshipMultiTenantOrganizationTenant | Format-List
   

   AddedByTenantId      : <OwnerTenantId>
   AddedDateTime        : 1/8/2024 8:05:25 PM
   DeletedDateTime      :
   DisplayName          : Berlin
   Id                   : <MtoJoinRequestIdB>
   JoinedDateTime       : 1/8/2024 9:53:55 PM
   Role                 : member
   State                : active
   TenantId             : <MemberTenantIdB>
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationMemberTransitionDetails
   AdditionalProperties : {[multiTenantOrgLabelType, none]}
   
   AddedByTenantId      : <OwnerTenantId>
   AddedDateTime        : 1/8/2024 7:47:45 PM
   DeletedDateTime      :
   DisplayName          : Cairo
   Id                   : <Id>
   JoinedDateTime       :
   Role                 : owner
   State                : active
   TenantId             : <OwnerTenantId>
   TransitionDetails    : Microsoft.Graph.Beta.PowerShell.Models.MicrosoftGraphMultiTenantOrganizationMemberTransitionDetails
   AdditionalProperties : {[multiTenantOrgLabelType, none]}
   

4. To allow for asynchronous processing, wait up to 2 hours before joining a multitenant organization is completed.

Microsoft Graph

1. In the member tenant, use the Update multiTenantOrganizationJoinRequestRecord API to join the multitenant organization.

   Request

   PATCH https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/joinRequest
   {
       "addedByTenantId": "{ownerTenantId}"
   }
   

2. Use the Get multiTenantOrganizationJoinRequestRecord API to verify the join.

   Request

   GET https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/joinRequest
   

   This operation takes a few minutes. If you check immediately after calling the API to join, the response will be similar to the following.

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/joinRequest/$entity",
       "id": "aa87e8a4-9c88-4e67-971d-79c9e43319a3",
       "addedByTenantId": "{ownerTenantId}",
       "memberState": "pending",
       "role": null,
       "transitionDetails": {
           "desiredMemberState": "active",
           "status": "notStarted",
           "details": ""
       }
   }
   

   After the join operation completes, the response is similar to the following.

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/joinRequest/$entity",
       "id": "aa87e8a4-9c88-4e67-971d-79c9e43319a3",
       "addedByTenantId": "{ownerTenantId}",
       "memberState": "active",
       "role": "member",
       "transitionDetails": null
   }
   

3. Use the List multiTenantOrganizationMembers API to check the multitenant organization itself. It should reflect the join operation.

   Request

   GET https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants
   

   Response

   {
       "@odata.context": "https://graph.microsoft.com/beta/$metadata#tenantRelationships/multiTenantOrganization/tenants",
       "value": [
           {
               "tenantId": "{memberTenantIdA}",
               "displayName": "Athens",
               "addedDateTime": "2023-11-20T21:24:59Z",
               "joinedDateTime": "2023-11-21T22:09:18Z",
               "addedByTenantId": "{ownerTenantId}",
               "role": "member",
               "state": "active",
               "transitionDetails": null
           },
           {
               "tenantId": "{memberTenantIdB}",
               "displayName": "Berlin",
               "addedDateTime": "2023-11-20T21:22:35Z",
               "joinedDateTime": "2023-11-21T21:55:34Z",
               "addedByTenantId": "{ownerTenantId}",
               "role": "member",
               "state": "active",
               "transitionDetails": null
           },
           {
               "tenantId": "{ownerTenantId}",
               "displayName": "Cairo",
               "addedDateTime": "2023-11-20T20:38:20Z",
               "joinedDateTime": null,
               "addedByTenantId": "{ownerTenantId}",
               "role": "owner",
               "state": "active",
               "transitionDetails": null
           }
       ]
   }
   

4. To allow for asynchronous processing, wait up to 2 hours before joining a multitenant organization is completed.

Step 8: (Optional) Leave the multitenant organization

Member tenant

You can leave a multitenant organization that you have joined. The process for removing your own tenant from the multitenant organization is the same as the process for removing another tenant from the multitenant organization.

If your tenant is the only multitenant organization owner, you must designate a new tenant to be the multitenant organization owner. For steps, see Step 4: (Optional) Change the role of a tenant.

PowerShell

• In the tenant, use the Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to remove the tenant. This operation takes a few minutes.

  Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId <MemberTenantId>
  

Microsoft Graph

• In the tenant, use the Remove multiTenantOrganizationMember API to remove the tenant. This operation takes a few minutes.

  Request

  DELETE https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{memberTenantId}
  

Step 9: (Optional) Delete the multitenant organization

Owner tenant

You delete a multitenant organization by removing all tenants. The process for removing the final owner tenant is the same as the process for removing all other member tenants.

PowerShell

• In the final owner tenant, use the Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant command to remove the tenant. This operation takes a few minutes.

  Remove-MgBetaTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId $OwnerTenantId
  

Microsoft Graph

• In the final owner tenant, use the Remove multiTenantOrganizationMember API to remove the tenant. This operation takes a few minutes.

  Request

  DELETE https://graph.microsoft.com/beta/tenantRelationships/multiTenantOrganization/tenants/{ownerTenantId}
  

Next steps

• Set up a multitenant org in Microsoft 365
• Synchronize users in multitenant organizations in Microsoft 365
• The new Microsoft Teams desktop client
• Configure multitenant organization templates using the Microsoft Graph API