# Managing tenants

Source: https://cumulocity.com/docs/enterprise-tenant/managing-tenants/
Sector: Platform administration
Release: Latest
Description: Create and manage subtenants, subscribe them to applications, and set custom properties, usage limits, tenant policies, and default subscriptions.

## Managing subtenants

Using the Enterprise tenant of Cumulocity, you can make use of the tenants functionality which allows you to create and manage subtenants.


> **Requirements:**
> APPLICATION ACCESS:
>
> The user must have access to the Administration application of an Enterprise tenant.
>
> ROLES & PERMISSIONS:
>
> The user must have at least one permission for the permission type "Tenant management":
> * To view all tenants: READ permission.
> * To create tenants: CREATE permission.
> * To edit tenants (including subscriptions) and to suspend or activate tenants: UPDATE permission.
> * To create tenants and perform activity permitted by UPDATE permission: ADMIN permission.




> **Important:**
> There is a major difference between providing several tenants and providing several users with different permissions within a single tenant. Tenants are physically separated data spaces with a separate URL, with own users, a separate application management and no sharing of data by default. Users in a single tenant by default share the same URL and the same data space. So if your users, for example, are separate customers of yours and you must strictly separate them because they may be competitors, we strongly recommend you to do so by working with tenants. For details on the role-based access approach versus multi-tenancy, see [RBAC versus multi-tenancy approach](https://cumulocity.com/docs/concepts/tenant-hierarchy/#comparison).




### To view subtenants {#to-view-subtenants}

Click **Subtenants** in the **Tenants** menu to view all subtenants available in your account.

The **Tenants** page provides the following information on each subtenant:

* The name of the subtenant, for example, company name of your customer.
* The ID and domain.
* Optionally, a contact name.
* The date when the tenant was created.
* The status of the tenant, either active (indicated by a green checkmark icon <i class="dlt-c8y-icon-ok text-success icon-20"></i>) or suspended (indicated by a red cross icon <i class="dlt-c8y-icon-block text-danger icon-20"></i>).


> **Info:**
> In the Management tenant, you also find a column with information on the parent tenant. The parent tenant is the original tenant that created the subtenants that are listed in the table.




### To create a subtenant {#to-create-a-subtenant}

1. Click **Create tenant** at the right of the top menu bar.

	![Create subtenant](https://cumulocity.com/docs/images/users-guide/enterprise-tenant/et-subtenant-create.png)

2. Provide the following properties:

	<table>
		<col style="width:20%">
		<col style="width:80%">
		<thead>
			<tr>
				<th style="text-align:left">Field</th>
				<th style="text-align:left">Description</th>
				<th style="text-align:left">Required</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td style="text-align:left">Domain/ URL</td>
				<td style="text-align:left">Enter a subdomain of your choice, for example "acme". The tenant's URL will be "acme.cumulocity.com" on cumulocity.com. You can only use one subdomain level. For example, you can only use "acme.cumulocity.com" on cumulocity.com. You cannot use "mycustomer.acme.cumulocity.com". This is not permitted by the TLS standard. <br> The tenant domain may contain lowercase letters, digits or hyphens (-). It must start with a letter; hyphens are only allowed in the middle; minimum is 2 characters.</td>
				<td style="text-align:left">Yes</td>
			</tr>
			<tr>
				<td style="text-align:left">Name</td>
				<td style="text-align:left">The name of the tenant, for example, the company's name.</td>
				<td style="text-align:left">Yes</td>
			</tr>
			<tr>
				<td style="text-align:left">Administrator's email</td>
				<td style="text-align:left">A valid email address to enable users to reset their password.</td>
				<td style="text-align:left">Yes</td>
			</tr>
			<tr>
				<td style="text-align:left">Administrator's username</td>
				<td style="text-align:left">Username for the administrator of this tenant.</td>
				<td style="text-align:left">Yes</td>
			</tr>
			<tr>
				<td style="text-align:left">Contact name</td>
				<td style="text-align:left">Name of the contact.</td>
				<td style="text-align:left">No</td>
			</tr>
			<tr>
				<td style="text-align:left">Contact phone</td>
				<td style="text-align:left">Phone number of the contact.</td>
				<td style="text-align:left">Yes</td>
			</tr>
			<tr>
				<td style="text-align:left">Send password reset link as email</td>
				<td style="text-align:left">Selected by default. If you deselect this option, you must provide a password and confirm the password (see <a href="https://cumulocity.com/docs/get-familiar-with-the-ui/user-settings/#to-change-your-password" class="no-ajaxy">To change your password</a> for more information on password strength).</td>
				<td>No</td>
			</tr>
			<tr>
				<td style="text-align:left">Tenant policy</td>
				<td style="text-align:left">You may select a tenant policy to be applied to the tenant from the dropdown list.</td>
				<td style="text-align:left">No</td>
			</tr>
		</tbody>
	</table>


3. Click **Save** to apply your settings.

When the subtenant is created, it gets an auto-generated ID, which cannot be changed. Also, it is automatically provisioned with a first, administrative user ("Administrator's username"). This administrator can create other users and set their permissions. The first user cannot be deleted to prevent you from locking yourself out.

From the Management tenant, you can enable other tenants to create subtenants. Contact your Operations team on how to configure this setting according to your needs.

### To view or edit subtenant properties {#to-view-or-edit-subtenant-properties}

Click on the desired subtenant or click the edit icon <i class="dlt-c8y-icon-edit1 text-primary icon-20"></i> at the right of the subtenant entry.

In the **Properties** tab, all fields are editable except of **ID**, **Domain/ URL**, **Administrator's username** and **Administrator's email**. For details on the fields, refer to [To create a subtenant](https://cumulocity.com/docs/enterprise-tenant/managing-tenants/#to-create-a-subtenant).

> **Info:**
> The **Administrator's email** may be changed by logging in to the subtenant with the **Administrator's username** and changing the own email.



To change the tenant password, click **Change password**, enter the new password in the upcoming fields and click **Save**.

#### Support user access information {#support-user-access-information}

At the right of the **Properties** tab, you can find information on the support user requests/access for the subtenants.

<img src="https://cumulocity.com/docs/images/users-guide/enterprise-tenant/et-support-user-properties.png" alt="Support user access information" style="max-width: 100%">

The following information is displayed here:

<table>
<colgroup>
<col width="20%">
<col width="80%">
</colgroup>
<thead>
<tr>
<th style="text-align:left">Field</th>
<th style="text-align:left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left">Status</td>
<td style="text-align:left">May be either "Enabled" or "Disabled". <br>"Enabled" indicates that: <br>&nbsp;&nbsp;- Support user access has been activated globally in the Management tenant.<br>&nbsp;&nbsp;- One or more subtenant users have activated support user access.<br>"Disabled" indicates that: <br>&nbsp;&nbsp;- Support user access has been deactivated globally in the Management tenant. <br>&nbsp;&nbsp;- No subtenant user has currently any active support user access (that means, each support user request has either expired or has actively been deactivated).</td>
</tr>
<tr>
<td style="text-align:left">Active requests count</td>
<td style="text-align:left">The number of requests currently active in the subtenant. Only displayed if support user access is not enabled globally in the Management tenant. Shown as a number in a small red dot.</td>
</tr>
<tr>
<td style="text-align:left">Expiry date</td>
<td style="text-align:left">Specifies the date on which support user access for the tenant will expire. If no date has been specified, the expiry date is set to "No limit".</td>
</tr>
</tbody>
</table>

### To suspend a subtenant {#to-suspend-a-subtenant}

Suspending a tenant blocks any access to this tenant, regardless whether the access is from devices, users or other applications. In addition, all its microservices are undeployed, and if the tenant is reactivated all its microservices are re-deployed.

Device-related data continues to be subject of the retention rules and will be gradually removed. The rest of the tenant's data remains in the Operational Store and can be made available later by clicking **Activate**.

Refer to [Lifecycle](https://cumulocity.com/docs/enterprise-tenant/usage-and-billing/#lifecycle) for details on the billing perspective of suspended tenants.


> **Important:**
> Suspended tenants for all Cumulocity public cloud instances will be automatically deleted after 60 days.




> **Info:**
> If data broker connectors are configured for a tenant, suspending this tenant results in suspending all its data broker connectors as well.



1. Click the menu icon <i class="dlt-c8y-icon-menu-vertical text-muted icon-20"></i> at the right of the respective subtenant entry and then click **Suspend**.

	![Suspend tenant](https://cumulocity.com/docs/images/users-guide/enterprise-tenant/et-subtenant-suspend.png)

2. In the resulting dialog box confirm the suspension by clicking **Suspend** and then entering your password.


> **Info:**
> * As part of suspending the tenant, an email is sent to the email address that was configured for the tenant administrator.
> * If you are a service provider, you can suppress this email.




### To delete a subtenant {#to-delete-a-subtenant}


> **Important:**
> Deleting a subtenant cannot be reverted. For security reasons, it is therefore only available in the Management tenant. You cannot delete tenants from any tenant but the Management tenant. Contact your Operations team for further support.
>
> Administrators in Enterprise tenants are only allowed to suspend active subtenants, but not to delete them.



Click the menu icon  <i class="dlt-c8y-icon-menu-vertical text-muted icon-20"></i> at the right of the respective subtenant entry and then click **Delete** to finally delete a tenant and remove all the data of the tenant.

## Subscribing applications

### Overview

Cumulocity features an application marketplace that allows tenants to access and manage various applications.

Management tenants and Enterprise tenants can control application access for their subtenants. In the **Applications** tab of a tenant, they can:

- [View and manage existing application subscriptions](https://cumulocity.com/docs/enterprise-tenant/managing-tenants/#to-view-subscribed-applications)
- [Subscribe applications to tenants](https://cumulocity.com/docs/enterprise-tenant/managing-tenants/#to-subscribe-an-application)
- [Monitor the microservice status](https://cumulocity.com/docs/enterprise-tenant/managing-tenants/#to-monitor-the-microservice-status)

For general information on applications as part of the Cumulocity ecosystem, refer to [Managing the ecosystem](https://cumulocity.com/docs/standard-tenant/ecosystem/#managing-applications).


> **Info:**
> Tenants can also create and deploy their own [custom applications](https://cumulocity.com/docs/standard-tenant/ecosystem/#custom-applications), which can be made available to their subtenants.



### To view subscribed applications {#to-view-subscribed-applications}

In the **Applications** tab of a tenant you can view all subscribed applications, subscribe applications to tenants, or remove the applications from the tenant. By default, the [standard Cumulocity applications](https://cumulocity.com/docs/standard-tenant/ecosystem/#applications-subscribed-by-default) are subscribed to the tenant.

A tenant can have multiple available applications as displayed under **Available applications** but to use an application's functionality a subscription to the application must be established for the tenant. The list of subscribed applications is shown under **Subscribed applications**.

<img src="https://cumulocity.com/docs/images/users-guide/enterprise-tenant/et-subtenant-applications.png" alt="Subscribe tenant" style="max-width: 100%">


> **Info:**
> Alternatively, you can retrieve the list of subscribed applications for a tenant by using the Cumulocity REST API to get [specific tenant information](https://cumulocity.com/api/core/#tag/Tenant-API). The subscribed applications will be listed under the <code>applications</code> fragment.



#### To view the application details {#to-view-the-application-details}

Expanding an application entry in the **Available applications** list shows the following details:

- Availability - One of MARKET, SHARED or PRIVATE
- Type - One of HOSTED, MICROSERVICE or EXTERNAL
- Owner - Tenant that owns the application


### To subscribe an application {#to-subscribe-an-application}

Hover over the application under **Available applications** at the right and click **Subscribe** on the desired application.

### To unsubscribe an application {#to-unsubscribe-an-application}

Hover over the application under **Subscribed applications** at the left and click **Unsubscribe**.

### To monitor the microservice status {#to-monitor-the-microservice-status}

For all applications hosted as microservices by Cumulocity the status of the application is indicated next to its name by symbols. It may be in one of the following states:

* <i class="dlt-c8y-icon-ok text-success icon-20"></i> Microservice is up and running.
* <i class="dlt-c8y-icon-exclamation-circle text-warning icon-20"></i> Microservice is unhealthy.
* <i class="dlt-c8y-icon-warning text-danger icon-20"></i> Microservice is down.

You can view details on the status by expanding the respective entry.

<img src="https://cumulocity.com/docs/images/users-guide/enterprise-tenant/et-application-details.png" alt="Application details">

The following information is provided:

* Active - the number of active microservice instances.
* Unhealthy - the number of inactive microservice instances.
* Desired - the number of desired microservice instances.
* Name - microservice instance name.
* Restarts - the number of microservice instance restarts.


> **Info:**
> Information on the microservice instance name and the number of restarts is displayed in case of at least one restart.



Further details are provided on the **Status** tab of the respective microservice, see [Monitoring microservices](https://cumulocity.com/docs/standard-tenant/ecosystem/#monitoring-microservices).

## Custom properties

The **Custom properties** tab allows you to view and edit values of tenant custom properties defined in the [properties library](https://cumulocity.com/docs/standard-tenant/changing-settings/#properties-library). Such properties are also displayed as columns in the [Usage statistics](https://cumulocity.com/docs/enterprise-tenant/usage-and-billing/) page.

## Setting limits

The **Limits** tab allows you to view and edit resource limits for the tenant, as well as to assign an "External reference" and to enable/disable the Gainsight product experience tracking.

### To limit the subtenant request rate {#to-limit-the-subtenant-request-rate}

Platform administrators can limit the request rate of each subtenant via the following properties:

* **Limit HTTP queue**: Limit of the HTTP request queue for the tenant.
* **Limit HTTP requests**: Limit of the HTTP requests for the tenant per second.
* **Limit stream queue**: Limit of the MQTT request queue for the tenant.
* **Limit stream requests**: Limit of the MQTT requests for the tenant per second.

The request throttling mechanism is only enabled when both HTTP properties (**Limit HTTP queue** and **Limit HTTP requests**) are configured. If one of the values is omitted, the other one is ignored and throttling remains disabled.


> **Important:**
> Rate limiting can be an effective countermeasure against threats like brute force login attempts, API abuse and request flooding thus reducing the number of malicious/unwanted traffic. This helps in protecting against DoS (Denial of Service) attacks and saving the available bandwidth for legitimate requests.



You can also customize the buffer size for the CEP queue and the data broker queue for a particular tenant. This can be done from the Management tenant. Contact your Operations team on how to configure this setting according to your needs.

### To limit the subtenant device number {#to-limit-the-subtenant-device-number}

Platform administrators can limit the count of concurrently registered root devices or simply all devices (including child devices) via the property **Limit number of devices**.

You can view the peak number of concurrently registered devices, root devices and the peak value of used storage in the [Usage statistics](https://cumulocity.com/docs/enterprise-tenant/usage-and-billing/) page.

### Product experience tracking {#product-experience-tracking}

In the parent tenant, check the checkbox **Enable Gainsight product experience tracking** to enable/disable the product experience tracking through the [Gainsight PX](https://www.gainsight.com/product-experience/) product experience software for the given child tenant.

At the tenant level, you can disable the product experience tracking by Gainsight by turning off the cookie banner on the **Branding** page. For more information, see [Branding](https://cumulocity.com/docs/enterprise-tenant/customization/#branding).

If you activate tracking for the tenant, its users are automatically tracked. However, the nature of this tracking depends on their consent. By accepting tracking, they permit the use of Personally Identifiable Information (PII) for tracking purposes. If they decline, their data is anonymized to ensure privacy, though tracking will still capture usage data without personal identifiers. For more details, see [Accessing and logging into the platform](https://cumulocity.com/docs/get-familiar-with-the-ui/platform-access).

## Tenant policies

A tenant policy is a set of tenant options and retention rules. Tenant options and retention rules may be specified during tenant creation.

Creating a tenant policy with a specific set of options and rules saves time when creating multiple tenants with the same settings.


> **Info:**
> The options and rules are copied into the tenant. Editing the policy has no effect on tenants that have already been created.




> **Important:**
> Tenant options specified in a tenant policy are **not encrypted**. You should not specify or overwrite tenant options here with a "credentials." prefix, since the platform expects those options to be encrypted with data that will appear after the tenant has been created.



### To view tenant policies {#to-view-tenant-policies}

Click **Tenant policies** in the **Tenants** menu to view all available tenant policies.

For each tenant policy, the name, an optional description and the number of options and retention rules is provided, either in a list or a grid.

### To create a tenant policy {#to-create-a-tenant-policy}

1. Click **Add policy** in the top menu bar.
2. In the resulting dialog box, enter a name and an optional description.
<br>![Add new policy](https://cumulocity.com/docs/images/users-guide/enterprise-tenant/et-tenant-policy-add.png)<br>
3. Add at least one retention rule. For details on creating retention rules, see [Retention rules](https://cumulocity.com/docs/standard-tenant/managing-data/#retention-rules).
4. Optionally, add a tenant option.
5. Click **Save**.

The tenant policy will be added to the tenant policies list.


> **Important:**
> When defining the retention rules and options you can select a checkbox to allow subtenants to modify definitions of these rules or options. By default, this checkbox is not activated. Be aware that if you do not select this checkbox after creating the subtenant you must run an update from the Management tenant in order to edit those rules and options.



### To edit a tenant policy {#to-edit-a-tenant-policy}

Click the respective policy entry or click the menu icon <i class="dlt-c8y-icon-menu-vertical text-muted icon-20"></i> at the right of the policy entry and then click **Edit**.

In the resulting dialog box, make your edits and click **Save** to save your settings.

To delete a retention rule or a tenant option from a policy, hover over it and click the remove icon <i class="dlt-c8y-icon-minus-circle text-danger icon-20"></i>.

### To duplicate a tenant policy {#to-duplicate-a-tenant-policy}

Click the menu icon <i class="dlt-c8y-icon-menu-vertical text-muted icon-20"></i> in the policy entry you want to duplicate and then click **Duplicate**.

### To delete a tenant policy {#to-delete-a-tenant-policy}

Click the menu icon <i class="dlt-c8y-icon-menu-vertical text-muted icon-20"></i> in the policy entry you want to delete and then click **Delete**.

## Default subscriptions

In the Cumulocity platform, you can configure which applications and microservices are subscribed to a tenant on tenant creation. When you create a new tenant, the specified applications and microservices automatically get subscribed to it.

In addition, you can specify which applications and microservices are subscribed to a tenant when the system is upgraded. This list might differ from the default subscriptions on tenant creation. For example, certain default applications might have been unsubscribed from a tenant after creation and you may not want these applications to be subscribed to it again or you may want to subscribe different ones to it.

### To view default subscriptions {#to-view-default-subscriptions}

In the **Default subscriptions** page, you can configure two separate lists of applications. These will be subscribed by default to:

- Every new tenant on its creation.
- Every existing tenant on platform upgrade.


> **Info:**
> These default lists can be overridden for particular subtenants by setting additional tenant options, for example via tenant policy. For details, see [Overriding default subscriptions](https://cumulocity.com/docs/enterprise-tenant/managing-tenants/#to-override-default-subscriptions) or the [Tenant API](https://cumulocity.com/api/core/#tag/Tenant-API) in the Cumulocity OpenAPI Specification.




> **Info:**
> Listing an application or microservice here only takes effect for a tenant if it is owned or shared as a MARKET application by that tenant's parent, or by the Management tenant if the tenant has no parent. The tenant's own ownership of, or a subscription it once had to, an application is not taken into account for this - only its parent's is.



On the left, the list of subscribable applications (both web applications and microservices) is displayed, which consists of:

- All own applications.
- All subscribed applications which have different names than the own applications.


> **Info:**
> In order to help you to distinguish which application is owned and which is subscribed, the tenant ID of the owner is displayed.



On the right, you see the **Subscribed on tenant creation** and the **Subscribed on platform upgrade** columns.

Initially, the lists show the default subscriptions inherited from the tenant hierarchy.

<img src="https://cumulocity.com/docs/images/users-guide/Administration/admin-default-subscriptions-inherited.png" alt="Default subscriptions - inherited from tenant hierarchy">

### To configure default subscriptions {#to-configure-default-subscriptions}

You can override both lists by switching the corresponding toggle. This will reveal all subscribable applications (initially, unselected ones are hidden) but the selection will remain the same.

Next, adjust the lists to your needs by selecting additional applications to be subscribed by default or deselect applications you do not want to be subscribed.

You may also deselect all of them if you don't want any subscriptions to be executed on tenant creation and/or platform upgrade.

<img src="https://cumulocity.com/docs/images/users-guide/Administration/admin-default-subscriptions-overridden.png" alt="Default subscriptions - overriding settings from tenant hierarchy">
<br>

If you want to return to the settings inherited from the tenant hierarchy, just switch the corresponding toggle again.

Save the settings by clicking **Save** at the bottom of the page.


> **Info:**
> Obsolete entries not matching any existing applications are removed on save. If an application selected in one of the lists has been removed, it will be silently ignored during tenant creation and/or platform upgrade. If another application with the same name is created afterwards (but before the settings on this page are saved again, which will remove the obsolete entry), the new application will be subscribed instead of the previous one.




### To override default subscriptions {#to-override-default-subscriptions}

The default subscriptions can be overridden for subtenants by setting up a tenant policy with the following options:

* To define default web applications subscribed to new tenants on creation:
  * category: configuration
  * key: default.tenant.applications
  * value: comma-separated list of application names, for example, administration,devicemanagement,cockpit,feature-microservice-hosting,feature-cep-custom-rules
* To define default microservices subscribed to new tenants on creation:
  * category: configuration
  * key: default.tenant.microservices
  * value: comma-separated list of microservice names, for example, device-simulator,report-agent,sms-gateway
* To use a different list of web applications to be subscribed to existing tenants on platform upgrade:
  * category: configuration
  * key: on-update.tenant.applications.enabled
  * value: true/false (when false or not set, the same list from default.tenant.applications will be used)
* To define default web applications subscribed to existing tenants on platform upgrade:
  * category: configuration
  * key: on-update.tenant.applications
  * value: comma-separated list of application names, for example, administration,devicemanagement,cockpit,feature-microservice-hosting,feature-cep-custom-rules
* To use a different list of microservices to be subscribed to existing tenants on platform upgrade:
  * category: configuration
  * key: on-update.tenant.microservices.enabled
  * value: true/false (when false or not set, the same list from default.tenant.microservices will be used)
* To define default microservices subscribed to existing tenants on platform upgrade:
  * category: configuration
  * key: on-update.tenant.microservices
  * value: comma-separated list of microservice names, for example, device-simulator,report-agent,sms-gateway