Configure a multitenant organization using the Microsoft Graph API (Preview)

Important

Multitenant organization is currently in PREVIEW. See the Product Terms for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

This article describes the key steps to configure a multitenant organization using the 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 (Preview) and Join or leave a multitenant organization in Microsoft 365 (Preview). To learn how to configure Microsoft Teams for your multitenant organization, see The new Microsoft Teams desktop client.

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

These steps describe how to use Microsoft Graph Explorer, but you can also use Postman, or 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

Icon for the owner tenant.
Owner tenant

  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

Icon for the owner tenant.
Owner tenant

  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

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

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 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: Wait

Icon for the member tenant.
Member tenant

  • To allow for asynchronous processing, wait a minimum of 2 hours between creation and joining a multitenant organization.

Step 7: 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 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 8: Join the multitenant organization

Icon for the member tenant.
Member tenant

  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 4 hours before joining a multitenant organization is completed.

Step 9: (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.

  • 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 10: (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.

  • 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