Getting Started with Tenancy Units

This page shows you the basic setup and workflow for tenancy units, part of Service Infrastructure, including:

The examples use direct calls to the Service Consumer Management REST API.

For general information about tenancy units, see Creating and Deleting Tenancy Units.

Before you begin

  • The Service Consumer Management API is intended for use with managed services and service producer projects. You'll need to already have a Google Cloud project and a managed service (such as a service created using Cloud Endpoints) in that project.
  • To use tenancy units, the Service Consumer Management API needs to create tenant projects in your service producer organization. Make sure that you have enough quota for the necessary number of service consumer projects.
  • Each service consumer project created in a tenancy unit must also be in a folder that you specify. Because of this, you need an Organization to use tenancy units.


Cloud APIs like the Service Consumer Management API only accept authenticated calls. If you don't have one already, find out how to create a service account and get a JSON key for authenticating to Cloud APIs in Getting Started with Authentication. If you're using a Google client library, you can set up your environment so that it uses your service account credentials by default. For direct calls to the REST API you'll need to provide an access token in each header, as in the following example:

    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" --header 'Content-Type: application/json' --data '{"tag":"tag1", "project_config":{"folder":"folders/9876543210", "tenant_project_policy": {"policy_bindings":{"role":"roles/owner", "members":""}}, "billing_config":{"billing_account":"billingAccounts/123456-472F22-28F9AA"}}}' -X POST ""

Creating a tenancy unit

After you have set the relevant permissions, when a service consumer enables your service you can create a tenancy unit that will hold the tenant project for that service consumer. A tenancy unit is a lightweight entity that represents the relationship of a service consumer - normally a Cloud project that enabled your APIs - and your managed service. Each service consumer can have only one active tenancy unit.

You create a tenancy unit as follows:


Here, 'projects/12345678901' is the service consumer project number, and is the name of your service.

The returned data structure has the name of the tenancy unit, with a generated unique id that can be used to access it. In this example, the generated name is /services/

Adding a tenant project

You can now add a project for the user. To add a new tenant project to the tenancy unit created in the previous step call the following method:


with the following data:

{"tag":"tag1", "project_config":{"folder":"folders/9876543210", "tenant_project_policy":{"policy_bindings":{"role":"roles/owner", "members":""}}, "billing_config":{"billing_account":"billingAccounts/123456-472F22-28F9AA"}}}

The tag value is an identifier you provide for the project within the tenancy unit: this can be anything you like (here it's tag1), such as a region, a consumer network, or just a string ID.

This call returns a long running operation that you can query to find if the project creation was successful.

If you need to apply a different configuration, for example to add new managed services, you can call the services.tenancyUnits.applyProjectConfig method.

Searching your tenancy units

Find a tenancy unit for a service consumer

To find a tenancy unit for a particular service consumer, use the ListTenancyUnits method, specifying their service consumer project number:


Search tenancy units

You can use the SearchTenancyUnits method to search for tenancy units defined for your service. For example, the following query will return all units that contain a project with the tag 'tag1':


Cleaning up tenancy units

When a service consumer stops using your service, deleting the tenancy unit cleans up resources and helps ensure your user's data is deleted.

Remove tenant projects

Tenant projects should be deleted before you delete the service consumer's associated tenancy unit. The removeProject method deletes the project and all resources in it:


with the following data:


Delete a tenancy unit

After all tenant projects in a tenancy unit have been removed, or if all of them are in a DELETED state, you can delete the unit: