> Source: https://builder-docs.ema.ai/administration/workspaces-tenants > Title: Workspaces & Tenants # Workspaces & Tenants > For foundational concepts on workspaces and tenants, see [Core Concepts: Workspaces & Tenants](/legacy-docs/core-concepts/workspaces-tenants). This page focuses on administrative tasks: tenant management models, parent-child relationships, and choosing the right architecture. * * * ## What Is a Tenant? A **tenant** is the fundamental unit of data isolation on the Ema platform. Each tenant has its own users, AI Employees, data, workflows, and configurations -- completely separated from every other tenant. Property Details **Data Isolation** Each tenant's data is fully isolated. No data flows between tenants unless explicitly configured. **Independent Users** Every tenant manages its own users and roles. Access to other tenants must be explicitly granted. **Dedicated AI Employees** AI Employees belong to a specific tenant and operate within that tenant's data boundaries. **Hierarchical Relationships** Tenants can be organized in parent-child hierarchies to enable template sharing and metrics rollup. * * * ## Tenant Roles Before configuring tenant hierarchies, understand the two levels of roles. ### Tenant-Level Roles Role Tenant Management Build Access Default AI Employee Role **Admin** Can invite users, view metrics Can build new AI Employees AI Employee Admin **Manager** Can invite users, view metrics No access AI Employee Manager **Builder** No privileges Can build new AI Employees; receives Admin role for AI Employees they create No access unless explicitly invited **Guest** No privileges No access No access unless explicitly invited ### AI Employee-Level Roles Role Management Workflow Access Audit Logs **Admin** Can invite users, view metrics Can edit workflow Can view **Manager** Can invite users, view metrics No access Can view **Builder** No privileges Can edit workflow No access **Guest** No privileges No access No access A user's tenant role determines their _default_ AI Employee role, but users can be granted different roles for specific AI Employees independently. For the full permission matrix, see [Governance, Access & Permissions](/legacy-docs/administration/governance-permissions). * * * ## Parent-Child Tenant Relationships Ema supports hierarchical tenant relationships where one tenant (the parent) can have one or more child tenants. ``` +--------------------+ | Parent Tenant | +---------+----------+ | +---------------+---------------+ v v v +---------------+ +---------------+ +---------------+ | Child Tenant | | Child Tenant | | Child Tenant | | A | | B | | C | +---------------+ +---------------+ +---------------+ ``` Capability Direction Details **User Access** Downward Parent users can access child tenants only on **explicit invitation**. Access is never automatic. **Template Sharing** Downward Parent tenants can share AI Employee templates to child tenants. **Metrics Aggregation** Upward Aggregated metrics roll up from child to parent via the tenant-scoped metrics dashboard. No PII or log data moves upward. Parent workspace administrators can view child-tenant metrics using the chip selectors on the Metrics page and drill into per-tenant detail tables. **Data & Logs** None No data flows between tenants in either direction. Each tenant's data is fully isolated. ### Constraints - A child tenant can have only **one parent**. - Tenant hierarchies can be **multiple levels deep** -- child tenants can have their own children. - Only a parent tenant's users can be invited to its **direct** child tenants. You cannot skip levels (a grandparent user must first be added to the parent, then to the child). * * * ## Tenant Management Models Partners and organizations can choose from four models depending on their business needs. ### Model 1: Standard -- Data Isolation per Company The most common and recommended model. Each company gets its own tenant. **When to use:** - Each customer requires full data isolation. - Customers may log into the Ema platform directly. - You need clear boundaries between customer environments. **Benefits:** Complete data isolation between all companies. Each customer manages their own users and AI Employees within their tenant. Partners can share templates downward to customer tenants. Clean, professional setup with real customer domains. ### Model 2: Multiple Tenants for the Same Company Internal separation by region, department, or business unit. **When to use:** - A single company needs data isolation between internal divisions. - Billing, data, or permission isolation between internal teams or regions is required. **Current limitation:** Every tenant requires a unique domain. Additional tenants for the same company must use a non-standard/placeholder domain (e.g., `company-us.co` instead of `company.com`). Consideration Detail Data Isolation Achieved between sub-tenants Domain Requirement Requires creating a non-standard/placeholder domain for additional tenants User Management Users from the parent tenant are added via the parent hierarchy Professionalism Placeholder domains may appear unprofessional to some customers > [INFO] > This model is a workaround for the current platform limitation of not having group-level isolation. A future platform enhancement for group-level permissions, metrics, and data isolation is planned. ### Model 3: Single Tenant Across Multiple Companies Best for embedded chatbots and API-only customers. **When to use:** - Customers interact via embedded chatbots, SDKs, or APIs -- they do not log into the Ema UI. - Customers are small or have lightweight use cases. - The partner fully manages all AI Employees on behalf of customers. **How data separation works:** AI Employees have inherent data separation -- unless explicitly connected, data does not flow between AI Employees. Individual workflow executions are isolated, so even a single AI Employee can safely service multiple customers. **Benefits:** Simplest setup with the lowest operational overhead. No need for customers to manage their own tenant. Partner retains full control over all configurations. **Trade-offs:** Customers cannot independently manage their AI Employees. Less granular control per customer compared to dedicated tenants. ### Model 4: Data Localization Across Geographies For data residency and compliance requirements. **When to use:** - Data must reside in a specific geographic region. - GDPR, data sovereignty, or similar legal constraints apply. > [WARNING] > **Important:** Sub-tenants do NOT solve data localization. All tenants within the same environment share the same underlying infrastructure and governance policies. True data localization requires a **completely separate Ema environment** in the target region. Tenants across different environments cannot communicate with each other. Separate environments are more expensive and require setup by the infrastructure team. * * * ## Choosing the Right Model Criteria Standard Multi-Tenant Single Tenant Geo-Localized **Data isolation** Full Full AI Employee / Runtime Full (per env) **Customer logs into UI** Yes Yes No Yes **Setup complexity** Low Medium Lowest Highest **Regulatory / data residency** No No No Yes **Best customer size** Any Large (internal separation) Small / Embedded Any (global) **Tenant domain** 1 real per customer May need placeholders Single partner domain 1 real per customer per region **Decision flow:** 1. Does the customer log into the Ema UI? - **No** -- Does the customer need dedicated data isolation? If no, use **Model 3** (Single Tenant). If yes, use **Model 1** (Standard). - **Yes** -- Does the company need internal team or region separation? If no, use **Model 1** (Standard). If yes, does it have data residency requirements? If no, use **Model 2** (Multi-Tenant). If yes, use **Model 4** (Geo-Localized). * * * ## Tenant Access: Current State and Future ### Current State -- Email Aliases When a partner user needs access to a child tenant, they must use an email alias (e.g., `admin1+acme@partner.com`) and log out/log in to switch between tenants. ### Future State -- Tenant Switcher An upcoming update will eliminate alias-based access: - Same email and user ID will work across all tenants. - A tenant switcher dropdown in the UI will enable instant switching without logging out. - Access to child tenants will still require explicit invitation. - Roles remain independently assigned per tenant. > [TIP] > **User Groups (future):** User Groups will allow bulk management of roles across the parent tenant, child tenants, and specific AI Employees simultaneously. * * * ## FAQs **What is the smallest unit of data isolation on the platform?** The **tenant** is the smallest unit of full data isolation. AI Employees also have data separation (data does not flow between AI Employees unless explicitly connected), and individual workflow executions have runtime isolation. There is no group-level isolation today. **Can I change a tenant's parent after it has been set?** A child tenant can only have one parent. Corrections are handled case-by-case. In the worst case, a new child tenant can be created and data migrated. **Do child tenants inherit users from the parent?** No. Users must be explicitly invited to each child tenant. **Can templates be shared upward from child to parent?** No. Templates can only be shared downward from parent to child tenants. **Can a child tenant have its own child tenants?** Yes. Tenant hierarchies can be nested to any depth. **How do I control whether a customer can build AI Employees?** Assign the appropriate tenant role. Manager and Guest roles have no build access; Admin and Builder roles allow building. **Does creating sub-tenants solve data localization (e.g., GDPR)?** No. All tenants within the same environment share the same infrastructure. Data localization requires a separate Ema environment in the target geography. **What happens to the "plus sign" email aliases after the tenant switcher update?** Existing alias-based accounts will be migrated. Going forward, the same primary email will be used across all tenants, and switching will happen via a dropdown in the UI. * * * ## Related Pages - [Governance, Access & Permissions](/legacy-docs/administration/governance-permissions) -- Full permission matrices. - [User Management](/legacy-docs/administration/user-management) -- Inviting users and assigning roles. - [AIE Audit Log](/legacy-docs/administration/audit-log) -- Track changes across your AI Employees.