Edit

Multitenant organization API overview

  • Article

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

The multitenant organization feature allows you to define an organization with more than one instance of Microsoft Entra ID. A multitenant organization enables multiple tenants to collaborate like a single entity.

Multitenant organization setup

In the directory, a multitenant organization represents a group of tenants that belong to your parent organization. This group of tenants is shared and agreed-upon between the tenant administrators through a collaborative setup process.

One tenant creates the multitenant organization. The tenant that creates the multitenant organization is assigned the multitenant organization role of owner. A multitenant organization owner has permissions to add tenants into a pending state, remove tenants from the multitenant organization, and change the role of any multitenant organization tenant.

To join the multitenant organization, pending tenants must submit a join request to join the multitenant organization and turn their multitenant organization status to active. Joined or active tenants typically start with the multitenant organization member role. Any multitenant organization member tenant has the permissions to leave the multitenant organization.

Cross-tenant access settings and templates

Cross-tenant access partner configurations and user synchronization settings are required between all tenant pairs in a multitenant organization. If they don't already exist at the time of any pending tenant joining a multitenant organization, partner configurations and user synchronization settings for any new tenant pairs will be autogenerated in an unconfigured state.

Optional multitenant organization templates for partner configurations and user synchronization settings, if configured, allow for the automatic modification of existing or autogenerated partner configurations and user synchronization settings for any new tenant pairs, at the time of such joining.

Multitenant organization size limitation

A multitenant organization has a default maximum of five active tenants, including owner tenants. If this maximum is exceeded by any submitted join request, the join request fails.

Also, at the time of joining, multitenant organization tenants can have a default maximum of 100,000 internal users per active tenant. If this maximum is exceeded at the time of any submitted join request, the join request fails.

If you need to increase these limits, you can submit a support request using the Azure portal or Microsoft Entra admin center. In your request, include the tenant ID of one owner tenant and a list of all tenant IDs that are intended to be part of the finalized multitenant organization.

Related content