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 Microsoft Teams desktop client.

Diagram that shows a multitenant organization with one owner tenant and two member tenants.

Prerequisites

Icon for the owner tenant.
Owner tenant

Icon for the member tenant.
Member tenant

Step 1: Sign in to the owner tenant

Icon for the owner tenant.
Owner tenant

  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"
    

Step 2: Create a multitenant organization

Icon for the owner tenant.
Owner tenant

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

Step 3: Add tenants

Icon for the owner tenant.
Owner tenant

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

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

Icon for the owner 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.

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

Step 5: (Optional) Remove a member tenant

Icon for the owner 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.

  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
    
    ...
    

Step 6: Sign in to a member tenant

Icon for the 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.

  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"
    

Step 7: Join the multitenant organization

Icon for the member tenant.
Member tenant

  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.

Step 8: (Optional) Leave the multitenant organization

Icon for the member tenant.
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.

Step 9: (Optional) Delete the multitenant organization

Icon for the owner tenant.
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.

Next steps