Create multitenant organization using Graph API


Multitenant organization

A multitenant organization is an organization which has more than one tenants, it means, it has more instances of Microsoft Entra ID.

Why to have multiple tenants? The most common reasons are:

  • Business: organizations with multiple subsidiaries or with acquired companies
  • Regulations: organizations with different compliance or regulatory needs or operating in multiple geographies
  • Testing: organizations with multiple tenants for development, testing or staging purposes

You can read more details about multitenant organization in the official Microsoft documentation.

Manage multitenant organization programmatically

Microsoft Graph API introduces a new Multitenant organization API. To be able to use this API on behalf of a user, the user must be either Security Administrator or Global Administrator.

Examples below require the Microsoft Graph PowerShell SDK, at least version 2.19 which is the first version that has cmdlets for managing the multitenant organization.

I will authenticate with a client secret through the Entra ID application with granted application permission MultiTenant.ReadWrite.All.

To connect with client secret:

$clientId = '<client_id>'
$tenantId = '<tenant_id>'
$secret = '<client_secret>'

$clientSecretCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $clientId, (ConvertTo-SecureString -String $secret -AsPlainText -Force)

Connect-MgGraph -ClientSecretCredential $clientSecretCredential -TenantId $tenantId -NoWelcome

Read properties of the multitenant organization

To read properties, call cmdlet Get-MgTenantRelationshipMultiTenantOrganization. The response contains properties like description, displayName or state.

Id                                   CreatedDateTime Description DisplayName State
--                                   --------------- ----------- ----------- -----
b5f05824-81ee-4daf-b341-2753eecf70ab                                         inactive

When the multitenant organization feature is not active, the state will be set to inactive.

Activate a new multitenant organization

To activate the multitenant organization feature, you need to setup display name and optionally description by using Set-MgTenantRelationshipMultiTenantOrganization cmdlet.

$params = @{
  displayName = "Martin Corp"
  description = "Tenants for development and testing"

Set-MgTenantRelationshipMultiTenantOrganization -BodyParameter $params

In the response, the property state is now active which indicates that the multitenant organization has been created successfully.

Id                                   CreatedDateTime      Description                         DisplayName State
--                                   ---------------      -----------                         ----------- -----
a9c5b810-44f2-4dc7-9e49-fbc3a8b0ce1e 5/10/2024 6:40:41 AM Tenants for development and testing Martin Corp active

Update the multitenant organization

For some unknown reason, there is no cmdlet for updating properties of existing multitenat organization. Cmdlets are auto-generated based on metadata exposed by the Graph API, so hopefully the next version of the PowerShell SDK will support the update.

I would expect cmdlet like Update-MgTenantRelationshipMultiTenantOrganization. The usage should be very similar to Set-MgTenantRelationshipMultiTenantOrganization.

List tenants in the multitenant organization

When you create a new multitenant organization, your tenant is automatically added to the multitenant organization as the owner.

Cmdlet Get-MgTenantRelationshipMultiTenantOrganizationTenant retrieves all tenants in the multitenant organization.


The response:

Id                                   AddedByTenantId   AddedDateTime        DisplayName JoinedDateTime Role  State  TenantId
--                                   ---------------   -------------        ----------- -------------- ----  -----  --------
086f77fd-e1a7-4d4b-8727-4d4a9f99b8ec 70cf0eca-e1e8..   5/10/2024 6:40:40 AM MSFT                       owner active 70cf0eca-e1e8...

There are two types of role for tenants:

  • owner: Can manage the multitenant organization. There can be multiple tenants with the owner role
  • member: Can only participate in a multitenant organization

The state of the tenant can be:

  • active: Tenant can participate in the multitenant organization
  • pending: Tenant was added to the multitenant organization, but the admin of the added tenant must submit join request to complete adding
  • removed: Tenant is being removed from the multitenant organization

You can filter tenants by either state or role, but not by both.

Get-MgTenantRelationshipMultiTenantOrganizationTenant -Filter "role eq 'owner'"

Get-MgTenantRelationshipMultiTenantOrganizationTenant -Filter "state eq 'pending'"

Even if the official documentation claims that filtering by tenantId is supported, in fact it's not.

Add tenant to the multitenant organization

Only the admin of a owner tenant can add other tenants to the multitenant organization. Id of the tenant to be added is required.

If you don't know the tenant id, you can use the endpoint findTenantInformationByDomainName and find the tenant id based on the domain name.

PowerShell SDK doesn't have cmdlet for this endpoint, but as an alternative, you can call the endpoint via Invoke-MgGraphRequest:

Invoke-MgGraphRequest -Method GET -Uri "'')"

The endpoint requires CrossTenantInformation.ReadBasic.All permission. The response contains tenant id.

Name                           Value
----                           -----
@odata.context       $metadata#microsoft.graph.tenantInformation
tenantId                       6babcaad-604b-40ac-a9d7-9fd97c0b779f
displayName                    Contoso, Ltd

So, let's try to add Contoso tenant to the multitenant organization via cmdlet New-MgTenantRelationshipMultiTenantOrganizationTenant.

$params = @{
  tenantId = "6babcaad-604b-40ac-a9d7-9fd97c0b779f"
  displayName = "Contoso, Ltd",
  role = "member"

New-MgTenantRelationshipMultiTenantOrganizationTenant -BodyParameter $params

I've specified tenant id, display name and the role.

The response from Get-MgTenantRelationshipMultiTenantOrganizationTenant will be

Id                                   AddedByTenantId   AddedDateTime        DisplayName  JoinedDateTime Role   State   TenantId
--                                   ---------------   -------------        -----------  -------------- ----   -----   --------
086f77fd-e1a7-4d4b-8727-4d4a9f99b8ec 70cf0eca-e1e8..   5/10/2024 6:40:40 AM MSFT                        owner  active  70cf0eca-e1e8...
efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f 70cf0eca-e1e8..   5/10/2024 8:11:12 AM Contoso, Ltd                member pending 6babcaad-604b...

The Contoso tenant is now in pending state until its admin will send join request. The admin can check the join request via Get-MgTenantRelationshipMultiTenantOrganizationJoinRequest.

Id                                   AddedByTenantId                      MemberState Role
--                                   ---------------                      ----------- ----
efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f 70cf0eca-e1e8-4d78-9d03-62ecf811dfc2 pending     member

We can see which tenant wants to add our tenant to the multitenant organization and what's the current state of the join request.

Confirm join request

To confirm the join request, use cmdlet Update-MgTenantRelationshipMultiTenantOrganizationJoinRequest and in the body set the addedByTenantId property to a tenant that added the current tenant to the multitenant organization.

$params = @{
  addedByTenantId = "70cf0eca-e1e8-4d78-9d03-62ecf811dfc2"

Update-MgTenantRelationshipMultiTenantOrganizationJoinRequest -BodyParameter $params

Remove tenants and delete the multitenant organization

An active member tenant can remove itself from the multitenant organization. An active owner tenant can remove any other tenant and itself. If the active owner remove itself and there is no other active tenant, it will delete the entire multitenant organization.

To remove the tenant, use Remove-MgTenantRelationshipMultiTenantOrganizationTenant cmdlet and specify id of the member to be removed returned by Get-MgTenantRelationshipMultiTenantOrganizationTenant in MultiTenantOrganizationMemberId parameter. Also tenant id can be used.

# for Contoso tenant, efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f represents id returned by Get-MgTenantRelationshipMultiTenantOrganizationTenant
Remove-MgTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId efc58e3a-4f4b-4f80-98c2-b7409f7e3e7f

# also tenant id is acceptable
Remove-MgTenantRelationshipMultiTenantOrganizationTenant -MultiTenantOrganizationMemberId 6babcaad-604b-40ac-a9d7-9fd97c0b779f
Buy Me a Coffee at
An error has occurred. This application may no longer respond until reloaded. Reload x