Skip to main content
Cortex provides a robust multi-tenant architecture with hierarchical tenant support, enabling you to build secure, scalable B2B platforms. Understanding the difference between tenant_id and sub_tenant_id is crucial for implementing proper data isolation and access control.

​
Understanding Tenant Hierarchy

​
Tenant ID (tenant_id) - Your Organization

The tenant_id is like your company’s main identifier. It represents the primary organizational unit - typically your main enterprise client or organization. This is the top-level identifier that provides the broadest scope of data isolation. Think of it as: The company name or organization ID that completely separates your data from all other organizations using Cortex.

​
Sub-Tenant ID (sub_tenant_id) - Your Department/Team

The sub_tenant_id represents a subdivision within a tenant - such as departments, teams, or individual customers within an enterprise. This enables hierarchical data organization and more granular access control. Think of it as: The department or team name within your company (like “Engineering”, “Sales”, or “HR”).

​
Default Sub-Tenant Behavior

Important: When you create a tenant, Cortex automatically creates a DEFAULT sub-tenant that acts as a global space for that tenant.
  • If you don’t specify a sub_tenant_id when using any API, your data will be stored in this default sub-tenant
  • This means if you upload documents with just a tenant_id and leave sub_tenant_id empty, they’ll go to the default sub-tenant
  • The default sub-tenant is perfect for organization-wide data that should be accessible across all departments

​
Creating Additional Sub-Tenants

No Explicit API Required: Cortex doesn’t require a separate API call to create sub-tenants. Sub-tenants are created automatically when you first use a new sub_tenant_id that doesn’t exist yet.

​
How Sub-Tenant Creation Works

  1. Automatic Creation: When you upload a document, text, or any content with a sub_tenant_id that doesn’t exist, Cortex automatically creates that sub-tenant
  2. First Upload Triggers Creation: The first API call with a new sub_tenant_id will create the sub-tenant and then process your content
  3. Immediate Availability: Once created, the sub-tenant is immediately available for all subsequent operations
Example - Creating a New Sub-Tenant: 
POST /upload/upload_document?tenant_id=acme_corp&sub_tenant_id=engineering_team_alpha
{
  "file": "engineering_standards.pdf",
  "document_metadata": {
    "title": "Engineering Standards",
    "department": "Engineering"
  }
}
If engineering_team_alpha doesn’t exist as a sub-tenant under acme_corp, Cortex will:
  1. ✅ Create the new sub-tenant engineering_team_alpha
  2. ✅ Upload and process the document
  3. ✅ Make the sub-tenant available for future operations

​
Sub-Tenant ID Best Practices

For User-Based Sub-Tenants (B2C): 
// Use user IDs as sub-tenant IDs for individual user workspaces
sub_tenant_id: "user_12345"
sub_tenant_id: "user_67890"
sub_tenant_id: "user_abc123"
For Department/Team-Based Sub-Tenants (B2B): 
// Use descriptive department names
sub_tenant_id: "engineering"
sub_tenant_id: "sales"
sub_tenant_id: "hr"
sub_tenant_id: "marketing"
For Project-Based Sub-Tenants: 
// Use project identifiers
sub_tenant_id: "project_alpha"
sub_tenant_id: "project_beta"
sub_tenant_id: "client_acme_corp"
For Customer-Based Sub-Tenants (Multi-tenant SaaS): 
// Use customer identifiers
sub_tenant_id: "customer_12345"
sub_tenant_id: "customer_acme_inc"
sub_tenant_id: "customer_beta_corp"

​
Best Practices for Sub-Tenant IDs

  1. Use Consistent Naming: Establish a clear naming convention across your application
  2. Include Prefixes: Use prefixes like user_, dept_, project_ to make the purpose clear
  3. Avoid Special Characters: Stick to alphanumeric characters and underscores
  4. Keep It Descriptive: Make sub-tenant IDs self-explanatory
  5. Consider Hierarchies: For complex organizations, consider hierarchical naming like dept_engineering_team_alpha
Good Examples: 
sub_tenant_id: "user_12345"           // Individual user
sub_tenant_id: "dept_engineering"     // Department
sub_tenant_id: "project_alpha_v2"     // Project
sub_tenant_id: "client_acme_corp"     // Client
sub_tenant_id: "team_mobile_dev"      // Team
Avoid These: 
sub_tenant_id: "12345"                // Too generic
sub_tenant_id: "user@company.com"     // Special characters
sub_tenant_id: "very_long_descriptive_name_that_is_hard_to_read" // Too long
sub_tenant_id: "temp"                 // Not descriptive

​
Multi-Tenant Architecture

What it is:
Cortex’s multi-tenant system creates completely isolated workspaces at both the tenant and sub-tenant levels. All documents, search results, embeddings, and AI memories are isolated per tenant/sub-tenant combination, ensuring zero cross-contamination of data. Key Benefits:
  • Complete Data Isolation: Zero cross-contamination between tenants and sub-tenants
  • Scalable B2B Architecture: Serve unlimited organizations and their subdivisions
  • Granular Access Control: Control data access at organization and department levels
  • Performance Optimization: Tenant-scoped searches for faster results
  • Compliance Ready: Meet enterprise security and privacy requirements

​
Real-World Use Cases

​
1. Enterprise SaaS Platform

Scenario: You’re building an AI knowledge assistant for multiple enterprise clients. 
Tenant: "acme_corp" (Acme Corporation)
├── Sub-tenant: "engineering" (Engineering Department)
├── Sub-tenant: "sales" (Sales Department)
├── Sub-tenant: "hr" (Human Resources)
└── Sub-tenant: "finance" (Finance Department)

Tenant: "tech_solutions" (Tech Solutions Inc.)
├── Sub-tenant: "product_dev" (Product Development)
├── Sub-tenant: "customer_success" (Customer Success)
└── Sub-tenant: "operations" (Operations)
Implementation:
  • Each enterprise client gets their own tenant_id
  • Each department within the enterprise gets their own sub_tenant_id
  • Documents uploaded by Acme’s Engineering team are only accessible to Acme Corporation (tenant_id: "acme_corp") and specifically to the Engineering department (sub_tenant_id: "engineering")

​
2. Consulting Firm with Multiple Clients

Scenario: A consulting firm serving multiple clients with project-based work. 
Tenant: "consulting_firm" (Your Consulting Firm)
├── Sub-tenant: "client_alpha" (Client Alpha Project)
├── Sub-tenant: "client_beta" (Client Beta Project)
├── Sub-tenant: "client_gamma" (Client Gamma Project)
└── Sub-tenant: "internal" (Internal Operations)
Implementation:
  • Your consulting firm is the main tenant_id
  • Each client project gets its own sub_tenant_id
  • Client Alpha’s documents are completely isolated from Client Beta’s data
  • Internal firm knowledge can be kept separate from client work

​
3. Educational Platform

Scenario: An AI-powered learning platform serving multiple schools. 
Tenant: "stanford_university" (Stanford University)
├── Sub-tenant: "computer_science" (CS Department)
├── Sub-tenant: "business_school" (Business School)
└── Sub-tenant: "medical_school" (Medical School)

Tenant: "mit" (MIT)
├── Sub-tenant: "engineering" (Engineering Department)
├── Sub-tenant: "sloan_school" (Sloan School of Management)
└── Sub-tenant: "media_lab" (Media Lab)
Implementation:
  • Each university is a separate tenant_id
  • Each department/school is a sub_tenant_id
  • Research papers and course materials are isolated by institution and department

​
4. Multi-Brand E-commerce

Scenario: A company managing multiple brands with different customer bases. 
Tenant: "fashion_group" (Fashion Group Corp)
├── Sub-tenant: "luxury_brand" (Luxury Brand)
├── Sub-tenant: "casual_brand" (Casual Brand)
└── Sub-tenant: "sports_brand" (Sports Brand)
Implementation:
  • The parent company is the tenant_id
  • Each brand is a sub_tenant_id
  • Customer data, product catalogs, and support documents are brand-specific

​
API Implementation

When making API calls, always include both identifiers: 
{
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "query": "What are our coding standards?",
  // other parameters...
}

​
Default Behavior

  • If sub_tenant_id is not provided, it automatically uses the DEFAULT sub-tenant created when the tenant was set up
  • This means the search/operation applies to the default sub-tenant scope (organization-wide data)
  • For tenant-wide operations, you can omit sub_tenant_id and your data will be stored in the default sub-tenant
  • The default sub-tenant acts as a global space where organization-wide documents and data are stored

​
Security and Isolation

​
Data Isolation Guarantees

  • Tenant Level: No data can ever cross tenant boundaries
  • Sub-Tenant Level: Data is isolated within sub-tenants unless explicitly queried at tenant level
  • Search Scope: All searches are automatically scoped to the specified tenant/sub-tenant
  • Memory Isolation: AI memories are completely isolated per tenant/sub-tenant combination

​
Access Patterns

  • Tenant-Wide Access: Use same value for both tenant_id and sub_tenant_id
  • Sub-Tenant Specific: Use specific sub_tenant_id within a tenant_id
  • Cross Sub-Tenant: Not supported - maintains strict isolation
This architecture ensures your platform can scale securely while maintaining the flexibility to organize data hierarchically within each client organization.