This page describes how to create, remove, and delete
[tenant projects](https://docs.cloud.google.com/service-infrastructure/docs/glossary.md.txt#tenant).

You use the Service Consumer Management API to create and configure tenant projects,
Google Cloud projects that are used to host your
[managed service](https://docs.cloud.google.com/service-infrastructure/docs/glossary.md.txt#managed) resources dedicated to a single
[service consumer](https://docs.cloud.google.com/service-infrastructure/docs/glossary.md.txt#consumer). Each tenant project is associated
with a [tenancy unit](https://docs.cloud.google.com/service-infrastructure/docs/glossary.md.txt#tenancy).

A tenancy unit can contain multiple tenant projects, each assigned a
`tag: string` identifier that you can use to indicate the purpose of the project
and to refer to it when deprovisioning.

After creation, a tenant project is just a Google Cloud project in your
organization. You can use any management tools to work with it as you would
normally use for Google Cloud project.

## Creating a tenant project

To create a tenant project and add it to a tenancy unit, call the
[`services.tenancyUnits.addProject`](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services.tenancyUnits/addProject.md.txt)
method.

The following example adds a new tenant project with the tag `tag1` to a tenancy
unit using the REST API:

```
POST https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/projects/12345678901/tenancyUnits/absdef:addProject
```

The call includes the following data:

```json
{"tag":"tag1", "project_config":{"folder":"folders/9876543210", "tenant_project_policy":{"policy_bindings":{"role":"roles/owner", "members":"user:bob@example.com"}}, "billing_config":{"billing_account":"billingAccounts/123456-472F22-28F9AA"}}}
```

This call returns a long running [operation](https://docs.cloud.google.com/service-infrastructure/docs/glossary.md.txt#operation) that you
can query to confirm the project creation was successful.

The new tenant project is configured with a project lien: a property set on the
tenant project to prevent accidental deletion. You must call the
[`services.tenancyUnits.removeProject`](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services.tenancyUnits/removeProject.md.txt)
method to release the lien and delete the project. It is not recommended to
bypass this protection.

The tenant project is created in the folder that you specified during
[Setup and Configuration](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/getting-started.md.txt).
It is not recommended to move a project to a different folder after it is
created.

The Service Consumer Management API service account is the creator and owner of tenant
projects, in addition to any other owners that are specified in the tenant
project configuration. It is not recommended to remove this account as an owner.

In some cases you might want to update an existing Google Cloud project to become a
tenant project rather than create a new tenant project. To add an existing
Google Cloud project to a tenancy unit, call the
[`services.tenancyUnits.attachProject`](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services.tenancyUnits/attachProject.md.txt)
method.

## Removing a tenant project

To remove a tenant project with the tag `abc`, call the
[`services.tenancyUnits.removeProject`](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services.tenancyUnits/removeProject.md.txt)
method as illustrated by the following example:

```
POST https://serviceconsumermanagement.googleapis.com/v1/services/your-service.example.com/projects/12345678901/tenancyUnits/absdef:removeProject
```

The call includes the following data:

```json
{"tag":"abc"}
```

This operation removes the project lien, deletes the project and all resources
in it, and deletes any associated metadata from the tenancy unit.

This deletes the project, and removes all metadata about it from the tenancy
unit. If you wish to delete the project, but keep a record of it, call the
[`services.tenancyUnits.deleteProject`](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services.tenancyUnits/deleteProject.md.txt)
method instead. This method deletes the project and retains the metadata,
annotating it with a state of `DELETED`. To undelete a deleted project, call the
[`services.tenancyUnits.undeleteProject`](https://docs.cloud.google.com/service-infrastructure/docs/service-consumer-management/reference/rest/v1/services.tenancyUnits/undeleteProject.md.txt)
method.