Sub-tenants

Sub-tenants allow you to create multi-level hierarchical structures within your tenant organization. This guide explains how sub-tenants work and how to manage them effectively:

A tenant can have multiple sub-tenants
Sub-tenants can have their own sub-tenants (nested hierarchy)
Each sub-tenant has exactly one parent (either a tenant or another sub-tenant)
Sub-tenants inherit certain configurations while maintaining independent control over others

A tenant can have multiple sub-tenants, and sub-tenants can nest further, but each sub-tenant has exactly one parent. Inheritance flows downward only: a sub-tenant can inherit users and roles from its parent (see Role Inheritance), and membership on a sub-tenant never grants access back up to the parent.

Creating Sub-tenants

Currently, the creation of sub-tenants is only supported through the Tenants page of the Descope Console or through our API.

You can create a sub-tenant in either of these places:

Inside a tenant: open the parent tenant, go to Settings → Sub-tenants, and create a child tenant there.
From the main Tenants page: create a new tenant, toggle on Create as sub-tenant, and select an existing tenant or sub-tenant as the parent.

When you create a sub-tenant, you can set Role Inheritance, which controls how the sub-tenant handles users and roles from its parent tenant:

Option	Behavior
Full Inheritance	Sync all users and assigned roles from the parent tenant
User only	Sync users from the parent; roles are assigned locally on the sub-tenant
None	Disable inheritance for both users and roles

Note

Inheritance only flows downward: roles or membership on a sub-tenant do not grant access to the parent.

Role Inheritance when creating from Settings → Sub-tenants

Role Inheritance when creating from the Tenants page

You can also manage existing sub-tenants from the Sub-tenants tab in the parent tenant's Settings. To see a complete hierarchy, including nested sub-tenants, you can select the Show all descendants checkbox.

Sub-tenant list

Sub-tenant Configurable Features

Sub-tenants support independent configuration of many features. See the relevant documentation for details:

Authentication and Session Settings

Authentication settings follow specific inheritance rules:

SSO Configuration: Can either be
- Inherited from the parent tenant (only group mapping and SSO domain are editable)
- Created independently for the sub-tenant
Password Settings: Always inherited from the parent tenant
Session Management: Always inherited from the parent tenant

JWT Structure

Sub-tenants appear as a flattened list in the JWT. Here is an example:

A user only has the explicit Partner role in Tenant 1, which has one associated sub-tenant Tenant 1 Sub-tenant:

Parent tenant assignment Sub-tenant assignment

JWT representation:

{
...
  "tenants": {
    "<Tenant 1 ID>": {
      "permissions": [],
      "roles": [
        "Partner"
      ]
    },
    "<Tenant 1 Sub-tenant ID>": {
      "permissions": null,
      "roles": [
        "Partner"
      ]
    }
  }
}

Was this helpful?