Tenants Module Documentation
Table of Contents
- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Sections
- Settings Reference
- Common Scenarios & Examples
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
---
1. Module Overview (Technical)
What Is the Tenants Module?
Tenants is a multi-tenant management module that creates and manages isolated organizations within the platform. Each tenant has its own SIP domain, user access, resource limits, branding, and data retention policies.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Tenants Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Tenant Definition │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Tenant: Acme Corporation │ │
│ │ │ │
│ │ Basic Info: │ │
│ │ ├─ Name: Acme Corporation │ │
│ │ ├─ Slug: acme-corp │ │
│ │ ├─ Admin Email: admin@acme.com │ │
│ │ └─ Status: Active │ │
│ │ │ │
│ │ Domain: │ │
│ │ ├─ SIP Domain: acme.pbx.company.com │ │
│ │ ├─ Voice Language: English │ │
│ │ └─ Timezone: America/New_York │ │
│ │ │ │
│ │ Privileges: │ │
│ │ ├─ Max Extensions: 100 │ │
│ │ ├─ Max Trunks: 10 │ │
│ │ ├─ Max Queues: 20 │ │
│ │ └─ Recording: Allowed │ │
│ │ │ │
│ │ Retention: │ │
│ │ ├─ Recordings: 90 days │ │
│ │ ├─ Voicemails: 60 days │ │
│ │ └─ CDR: 365 days │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Creates isolated resources │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Tenant Resources │ │
│ │ │ │
│ │ ├─ SIP Domain (FreeSWITCH) │ │
│ │ ├─ Extensions, Ring Groups, Queues │ │
│ │ ├─ Users, Roles │ │
│ │ ├─ Routing (Inbound, Outbound, IVR) │ │
│ │ ├─ Recordings, Voicemails, CDR │ │
│ │ └─ Branding (Logo, Colors) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Key Tables
| Table | Purpose |
|---|
public.tenants | Tenant records | |
public.user_tenants | User-tenant mapping | |
telephony.domains | SIP domains |
Key Files
| File | Description |
|---|
modules/tenants/ | Frontend module |
2. Module Overview (Commercial/Business)
Business Value
Tenants provides complete isolation:
| Without Tenants | With Tenants |
|---|
| Single organization | Multiple organizations | |
| Shared resources | Isolated resources | |
| No limits | Resource quotas | |
| Single billing | Per-tenant capacity |
Use Cases
- Service Provider
- Multiple customers
- Per-customer billing
- Enterprise Departments
- Separate divisions
- Isolated management
- Reseller Model
- White-label tenants
- Customer self-management
- Compliance
- Data isolation
- Separate retention
Feature Highlights
| Feature | Benefit |
|---|
| Slug Identifier | Unique URL/API access | |
| SIP Domain | Isolated telephony | |
| Resource Limits | Capacity control | |
| Retention Policies | Storage management | |
| User Access | Admin assignment | |
| Branding | Custom appearance |
3. Module Overview (End User/Administrator)
What Can You Do?
- Create new tenants
- Configure SIP domains
- Set resource limits (extensions, trunks, queues)
- Assign tenant administrators
- Configure data retention
- Enable/disable tenants
- Duplicate existing tenants
Tenants Interface
┌─────────────────────────────────────────────────────────────────┐
│ Tenants │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Manage multi-tenant organizations │
│ │
│ [+ Add Tenant] │
│ │
│ [🔍 Search tenants...] │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Tenant Name │ Slug │ Users │ Status │ Created │ │
│ ├─────────────────┼────────────┼───────┼─────────┼─────────┤ │
│ │ Main ⭐ │ main │ 5 │ ● Active│ 2024-01 │ │
│ │ Acme Corp │ acme-corp │ 25 │ ● Active│ 2024-06 │ │
│ │ Beta Inc │ beta-inc │ 10 │ ● Active│ 2024-08 │ │
│ │ Test Tenant │ test │ 2 │ ○ Inactive│ 2024-10│ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ⭐ = Primary Tenant (cannot be deleted) │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Add Tenant │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Tenant Information] [Domain Configuration] [User Access] │
│ │
│ ▼ Basic Information │
│ │
│ Tenant Name: [Acme Corporation ] │
│ │
│ Slug: [acme-corp ] │
│ Lowercase letters, numbers, and hyphens only │
│ │
│ Admin Email: [admin@acme.com ] │
│ │
│ Enabled: ✓ │
│ │
│ ──────────────────────────────────────────────────────────────│
│ │
│ ▼ Appearance │
│ │
│ Primary Color: [#3B82F6 ] [🎨] │
│ Secondary Color: [#64748B ] [🎨] │
│ Logo: [Upload...] │
│ Favicon: [Upload...] │
│ │
│ ──────────────────────────────────────────────────────────────│
│ │
│ ▼ Localization │
│ │
│ Default Locale: [English (US) ▼] │
│ Timezone: [America/New_York ▼] │
│ │
│ ──────────────────────────────────────────────────────────────│
│ │
│ ▼ Telephony Privileges │
│ │
│ Max Extensions: [100 ] Max Trunks: [10 ] │
│ Max Queues: [20 ] Max IVR: [10 ] │
│ Max Conferences: [5 ] Max Parking Lots: [5 ] │
│ Allow Recording: ✓ │
│ │
│ ──────────────────────────────────────────────────────────────│
│ │
│ ▼ Recording Retention │
│ │
│ Delete Oldest Recordings: [90 ] days │
│ Delete Oldest Voicemails: [60 ] days │
│ Delete Oldest CDR: [365 ] days │
│ │
│ [Next: Domain Configuration] │
│ │
└─────────────────────────────────────────────────────────────────┘
Add/Edit Tenant - Domain Configuration Tab
┌─────────────────────────────────────────────────────────────────┐
│ Add Tenant │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Tenant Information] [Domain Configuration] [User Access] │
│ │
│ Configure the telephony domain for this tenant │
│ │
│ Domain Name: [acme.pbx.company.com ] │
│ Unique SIP domain (realm) for SIP registration │
│ │
│ Description: [Acme Corporation PBX ] │
│ Brief description for identification │
│ │
│ Voice Language: [English ▼] │
│ Language for voice prompts and announcements │
│ │
│ Default Timezone: [America/New_York ▼] │
│ Sets the local timezone for voicemail and call logs │
│ │
│ Default Country Code: [+1 (US) ▼] │
│ Used for caller ID normalization (E.164 format) │
│ │
│ [Back] [Next: User Access] │
│ │
└─────────────────────────────────────────────────────────────────┘
Add/Edit Tenant - User Access Tab
┌─────────────────────────────────────────────────────────────────┐
│ Add Tenant │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Tenant Information] [Domain Configuration] [User Access] │
│ │
│ Configure user access for this tenant │
│ │
│ ○ Use Current User │
│ Use the current logged-in user as the tenant administrator │
│ │
│ ● Create New │
│ │
│ ──────────────────────────────────────────────────────────────│
│ │
│ Username: [acme.admin ] │
│ Email: [admin@acme.com ] │
│ Password: [•••••••••• ] │
│ Full Name: [John Smith ] │
│ Department: [IT ] │
│ │
│ Locale: [English (US) ▼] │
│ Timezone: [America/New_York ▼] │
│ Startup Dialog: [Dashboard ▼] │
│ │
│ TOTP Enabled: ☐ Active: ✓ │
│ │
│ [Back] [Create Tenant] │
│ │
└─────────────────────────────────────────────────────────────────┘
Quick Tips
TIP
Slug Format: Use lowercase, hyphens. Example:
acme-corp.
TIP
Domain Name: Must be unique SIP realm.
WARNING
Primary Tenant: The main tenant cannot be deleted.
---
4. Configuration Sections
| Field | Description |
|---|
| Tenant Name | Display name | |
| Slug | Unique URL identifier | |
| Admin Email | Contact email | |
| Enabled | Active/Inactive |
Appearance
| Field | Description |
|---|
| Primary Color | Main accent | |
| Secondary Color | Background accent | |
| Logo | Tenant logo | |
| Favicon | Browser icon |
Localization
| Field | Description |
|---|
| Default Locale | UI language | |
| Timezone | Default timezone |
Telephony Privileges
| Field | Description |
|---|
| Max Extensions | Extension limit | |
| Max Trunks | Trunk limit | |
| Max Queues | Queue limit | |
| Max IVR | IVR menu limit | |
| Max Conferences | Conference limit | |
| Max Parking Lots | Parking lot limit | |
| Allow Recording | Enable/disable recording |
Recording Retention
| Field | Description |
|---|
| Delete Oldest Recordings | Days to keep recordings | |
| Delete Oldest Voicemails | Days to keep voicemails | |
| Delete Oldest CDR | Days to keep call records |
Domain Configuration
| Field | Description |
|---|
| Domain Name | SIP domain (realm) | |
| Description | Domain description | |
| Voice Language | Prompt language | |
| Default Timezone | Call log timezone | |
| Default Country Code | E.164 normalization |
User Access
| Field | Description |
|---|
| Use Current User | Assign current user | |
| Create New | Create new admin | |
| Username | Login username | |
| Email | User email | |
| Password | User password | |
| Full Name | Display name |
5. Settings Reference
Resource Limit Guidelines
| Resource | Small | Medium | Large |
|---|
| Extensions | 25 | 100 | 500+ | |
| Trunks | 2 | 10 | 50+ | |
| Queues | 5 | 20 | 100+ | |
| IVR | 3 | 10 | 50+ | |
| Conferences | 2 | 5 | 20+ |
Retention Guidelines
| Data Type | Minimum | Recommended | Maximum |
|---|
| Recordings | 30 days | 90 days | 365 days | |
| Voicemails | 30 days | 60 days | 180 days | |
| CDR | 90 days | 365 days | Unlimited |
Slug Requirements
| Rule | Example |
|---|
| Lowercase | ✓ acme-corp | |
| No spaces | ✗ acme corp | |
| Hyphens allowed | ✓ acme-corp | |
| Numbers allowed | ✓ acme123 | |
| No special chars | ✗ acme_corp |
6. Common Scenarios & Examples
Scenario 1: Create New Customer Tenant
- Click Add Tenant
- Name = "Acme Corporation"
- Slug = "acme-corp"
- Set Enabled = ✓
- Configure limits (extensions, trunks)
- Set retention policies
- Next: Configure domain
- Next: Create admin user
- Save
Scenario 2: Duplicate Existing Tenant
- Find similar tenant
- Click Duplicate
- Change name and slug
- Adjust limits as needed
- Save as new tenant
Scenario 3: Disable Tenant
- Edit tenant
- Enabled = ☐
- Save
- Users can't access, data preserved
Scenario 4: Update Resource Limits
- Edit tenant
- Increase Max Extensions
- Increase Max Trunks
- Save
- New limits apply immediately
---
7. Limitations & Important Notes
Technical Notes
NOTE
Primary Tenant: Cannot be deleted or disabled.
NOTE
Slug Immutable: Cannot change after creation.
WARNING
Domain Unique: Each tenant needs unique SIP domain.
Best Practices
- Meaningful Slugs: Use company name
- Conservative Limits: Start small, increase as needed
- Retention Balance: Storage vs. compliance
- Admin Assignment: Always assign an admin
- Test First: Create test tenant before production
Multi-Tenant Isolation
| Isolated | Shared |
|---|
| Extensions | System settings | |
| Routing | Templates | |
| Users (per tenant) | Global users | |
| CDR | Certificates | |
| Recordings | HTTP server |
8. Troubleshooting Tips
Common Issues
| Symptom | Possible Cause | Solution |
|---|
| Slug exists | Duplicate slug | Use different slug | |
| Domain exists | Duplicate domain | Use different domain | |
| Can't delete | Primary tenant | Cannot delete main | |
| User can't access | Tenant disabled | Enable tenant |
Check Tenant
SELECT
name,
slug,
is_enabled,
max_extensions,
max_trunks
FROM public.tenants
WHERE slug = 'acme-corp';
Check Domain
SELECT
domain,
description,
language
FROM telephony.domains
WHERE tenant_id = 'tenant-uuid';
---
9. Glossary
| Term | Definition |
|---|
| Tenant | Isolated organization | |
| Slug | URL-safe identifier | |
| SIP Domain | Telephony realm | |
| Privileges | Resource limits | |
| Retention | Data lifecycle | |
| Multi-tenant | Multiple organizations |
Lua Script Status ℹ️
Administration Module
| Component | Status |
|---|
| Tenants | ℹ️ Multi-tenant management - no Lua handler required |
---
Documentation last updated: January 2026
