> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenant Management

> Manage your KnoxCall tenant settings, base URL, subdomain, and organization details. Control tenant-level configuration and security.

# Tenant Management

Configure your KnoxCall tenant settings, subdomain, and organization details.

## What is a Tenant?

A **tenant** is your organization's isolated KnoxCall instance:

* 🏢 Dedicated subdomain: `{slug}.knoxcall.com`
* 🔒 Isolated data (routes, secrets, clients)
* 👥 Team members with specific access
* 📊 Separate analytics and logs
* 💳 Individual subscription plan

**Multi-tenancy:** You can create multiple tenants for different projects, clients, or environments.

## Tenant Settings

Navigate to **Settings** → **Profile** to manage tenant settings.

<Note>
  The settings sidebar is **deployment-mode aware**. Cloud-only sections — **Integrations**, **Deployment**, **Billing**, **Team**, and **Referrals** — are hidden when running a self-hosted KnoxCall instance. The sections visible to you depend on your `DEPLOYMENT_MODE` environment variable.
</Note>

### Tenant Name

**Display name** for your organization

**Example:**

```text theme={"dark"}
Dunder Mifflin Paper Company
```

**Used in:**

* Admin UI header
* Email notifications
* Invoices

**To change:**

1. Navigate to Settings → Profile
2. Edit "Tenant Name" field
3. Click Save

### Tenant Slug

**URL-friendly identifier** for your tenant

**Example:**

```text theme={"dark"}
DunderMifflin
```

**Used in subdomain:**

```text theme={"dark"}
https://DunderMifflin.knoxcall.com
```

**To change:**

1. Navigate to Settings → Profile
2. Edit "Slug" field
3. Click Save

**Note:** Changing slug updates your base URL. Clients must update to new URL.

### Base URL

**Your unique KnoxCall proxy URL:**

```text theme={"dark"}
https://{slug}.knoxcall.com/api
```

**Example:**

```text theme={"dark"}
https://DunderMifflin.knoxcall.com/api
```

This is where clients send proxy requests. Append the route path after `/api/`,
e.g. `https://DunderMifflin.knoxcall.com/api/v1/users`.

The same `{slug}.knoxcall.com` host serves the admin UI (browser) and the
proxy API (under `/api/`). API requests are authenticated with the
`x-knoxcall-key` header.

## Profile Photo and Address

The account profile page (Settings → Profile) supports photo upload and address fields.

### Profile photo

* **Upload**: click your current avatar → **Upload photo** (JPEG or PNG, max 2 MB)
* **Remove**: hover over your avatar → click **Remove photo**

Your profile photo appears in the admin UI header and in team membership lists.

### Address fields

Address information is used for billing and compliance:

| Field              | Notes                                              |
| ------------------ | -------------------------------------------------- |
| **Country**        | Required for billing — affects VAT/tax calculation |
| **Street address** | Autocompletes via Google Places                    |
| **City**           | Auto-filled from Google Places selection           |
| **Postal code**    | Auto-filled from Google Places selection           |

Type your address in the street field and select from the Google Places autocomplete dropdown to fill all address fields at once.

## Tenant Features

Different subscription plans include different features:

### Starter Plan

* ✅ Unlimited routes
* ✅ Basic analytics (7 days)
* ✅ Email alerts
* ✅ API logs (7 days)

### Pro Plan

* ✅ Everything in Starter
* ✅ Advanced analytics (30 days)
* ✅ SMS + Slack alerts
* ✅ Log export (CSV)
* ✅ Real-Time Geo

### Enterprise Plan

* ✅ Everything in Pro
* ✅ Extended retention (90 days)
* ✅ Audit logs (1 year)
* ✅ Custom integrations
* ✅ Priority support

**View your plan:** Settings → Billing

## Tenant Deletion

**⚠️ DESTRUCTIVE:** Deleting tenant is permanent!

**What's deleted:**

* All routes and configurations
* All secrets (encrypted credentials)
* All clients and IP whitelists
* All API keys
* All logs and analytics
* All team members
* All billing history

**Cannot be undone!**

**To delete:**

1. Navigate to Settings → Profile
2. Scroll to "Danger Zone"
3. Click "Delete Tenant"
4. Type tenant name to confirm
5. Click "I understand, delete this tenant"

**Recommendations:**

* Export all data before deletion
* Revoke all API keys
* Notify team members
* Cancel subscription

## Multi-Tenant Setup

**Use cases for multiple tenants:**

### Scenario 1: Separate Dev/Staging/Production

```text theme={"dark"}
Tenant 1: DunderMifflin-Dev (testing)
Tenant 2: DunderMifflin-Staging (pre-prod)
Tenant 3: DunderMifflin-Prod (live)
```

**Benefits:**

* Isolated configurations
* No risk of prod changes during dev
* Separate team access

### Scenario 2: Multiple Clients/Projects

```text theme={"dark"}
Tenant 1: ClientA-Integration
Tenant 2: ClientB-Integration
Tenant 3: Internal-APIs
```

**Benefits:**

* Client isolation
* Separate billing
* Per-client customization

### Scenario 3: Regional Tenants

```text theme={"dark"}
Tenant 1: Company-US
Tenant 2: Company-EU
Tenant 3: Company-Asia
```

**Benefits:**

* Geographic compliance (GDPR, etc.)
* Regional routing
* Performance optimization

## Switching Between Tenants

**If you have access to multiple tenants:**

1. Click tenant dropdown (top-left of admin UI)
2. Select different tenant
3. UI updates to show selected tenant's data

**Each tenant has:**

* Own routes, secrets, clients
* Own team members
* Own billing

## Best Practices

### 1. Use Descriptive Names

✅ **Good:** Dunder Mifflin Production
❌ **Bad:** Tenant 1

### 2. Protect Production Tenants

**Recommendations:**

* Limit team member access
* Enable all security features
* Regular audit log reviews
* Never test in production tenant

### 3. Document Tenant Purpose

**Maintain documentation:**

```text theme={"dark"}
Tenant: DunderMifflin-Prod
Purpose: Production API proxy for customer-facing apps
Team: ops@example.com, john@example.com
Subdomain: https://a1b2c3d4.DunderMifflin.knoxcall.com
Critical Routes: payments, orders, fulfillment
```

### 4. Regular Security Reviews

**Monthly:**

* Review team member access
* Check API key usage
* Audit configuration changes
* Verify secrets rotated

### 5. Plan for Tenant Migration

**If moving to new tenant:**

1. Create new tenant
2. Replicate routes, secrets, clients
3. Test thoroughly in new tenant
4. Update clients to new subdomain
5. Monitor old tenant for stragglers
6. Deprecate old tenant after grace period

## Related Features

* **Team Management**: Invite team members to tenant
* **API Keys**: Manage tenant-level authentication
* **Subscription**: Billing and plan management

## Next Steps

<CardGroup cols={2}>
  <Card title="Team Collaboration" icon="users" href="/account/team-collaboration">
    Invite team members
  </Card>

  <Card title="Subscription Plans" icon="credit-card" href="/account/subscription-plans">
    Manage billing
  </Card>

  <Card title="API Keys" icon="key" href="/getting-started/quick-start-guide">
    Create authentication keys
  </Card>

  <Card title="Routes" icon="route" href="/getting-started/first-route">
    Configure your routes
  </Card>
</CardGroup>

***

<CardGroup cols={2}>
  <Card title="📊 Statistics" icon="chart-line">
    * **Level**: beginner
    * **Time**: 5 minutes
  </Card>

  <Card title="🏷️ Tags" icon="tags">
    `tenant`, `organization`, `admin`, `settings`
  </Card>
</CardGroup>