---
title: Introduction
slug: api-documentation/introduction
docTags: 
createdAt: 2026-10-19T10:26:54.944Z
---

## Overview

The Tenant Management API provides complete control over tenant provisioning, configuration, and lifecycle management within the NoChannel e-commerce platform. This API is the foundation of the platform's multi-tenancy architecture, enabling you to create and manage isolated business environments with their own sites, configurations, and administrative access.

## What is a Tenant?

A **tenant** represents a complete, isolated e-commerce business within the NoChannel platform. Each tenant has:

- **Unique Identity**: A distinct tenant ID and domain for administrative portal access
- **Data Isolation**: Complete separation from other tenants' data and operations
- **One or More Sites**: Customer-facing storefronts or sales channels
- **Custom Configuration**: Tenant-specific settings, integrations, and branding
- **Independent Administration**: Separate user management and access control

Think of a tenant as a complete e-commerce company or business unit. For example, "Acme Retail" would be a tenant that might operate multiple storefronts (sites) like "Acme US Store", "Acme EU Store", and "Acme Mobile App".

## What is a Site?

A **site** represents a customer-facing storefront or sales channel within a tenant. Sites enable multi-channel commerce where a single business can operate:

- **Multiple Storefronts**: Separate stores for different regions, brands, or customer segments
- **Multiple Channels**: Web, mobile, B2B portals, marketplace integrations
- **Independent Configuration**: Each site can have its own URL, activation schedule, and site-specific settings
- **Shared Resources**: Sites within a tenant share catalog, customer data, and backend systems

For example, a tenant "Global Retail Corp" might have sites for "US Store" (shop-us.globalretail.com), "UK Store" (shop-uk.globalretail.com), and "B2B Portal" (b2b.globalretail.com).

## Key Concepts

### Multi-Tenancy Architecture

The platform uses a true multi-tenant architecture where each tenant's data is completely isolated. Tenants cannot access or interfere with each other's operations, ensuring security and data privacy. This enables:

- **White-label Solutions**: Each tenant can brand their administrative portal and storefronts independently
- **Scalability**: Add new businesses without infrastructure changes
- **Cost Efficiency**: Shared platform infrastructure with isolated business logic

### Domain Management

Each tenant receives a unique **domain** (subdomain) for accessing their administrative portal. This domain:

- Must be globally unique across all tenants
- Forms the admin portal URL (e.g., `acme.upstartcommerce.com`)
- Cannot be changed easily once set (requires coordination with users)
- Is separate from site URLs (which are customer-facing)

### Site Lifecycle Management

Sites support sophisticated lifecycle controls:

- **Activation Dates**: Schedule when a site becomes accessible
- **Deactivation Dates**: Schedule when a site closes
- **Enabled Flag**: Immediate manual override to enable/disable
- **Archive Status**: Soft-delete sites while preserving historical data

These controls enable use cases like seasonal stores, scheduled launches, maintenance windows, and gradual rollouts.

## Common Use Cases

### Creating a New Business Tenant

1. Create a tenant with initial site(s) using `POST /v1/tenants/create`
2. Tenant admin receives verification email
3. Admin completes verification to activate the tenant
4. Begin configuring catalog, users, and integrations

### Managing Multiple Storefronts

1. Create additional sites for a tenant using `POST /v1/tenants/{tenantId}/sites`
2. Configure site-specific settings (URLs, activation dates)
3. Apply site-specific configurations (payment gateways, shipping methods)
4. Monitor and update sites independently

### Scheduled Site Launch

1. Create site with future `activationDate`
2. Configure all site settings while inactive
3. Site automatically becomes accessible at scheduled time
4. Optionally set `deactivationDate` for limited-time stores

### Emergency Site Shutdown

1. Update site with `enabled: false` using `PUT /v1/tenants/{tenantId}/sites/{siteId}`
2. Site becomes immediately inaccessible (independent of activation dates)
3. Re-enable when issue is resolved with `enabled: true`

### Tenant Rebranding

1. Update tenant name and/or domain using `PUT /v1/tenants/{tenantId}`
2. Coordinate with users regarding new portal URL if domain changed
3. Site URLs remain unchanged (update separately if needed)

## API Organization

The API is organized into these functional areas:

### Tenant Operations

- Create, retrieve, update, and delete tenants
- Manage tenant verification and activation
- Query tenants by ID or domain
- Retrieve audit history for compliance

### Site Operations

- Create and manage sites within a tenant
- Control site lifecycle (activation, deactivation, archival)
- Update site configuration and URLs
- Query site status and configuration

### Configuration Management

- Retrieve Cloudinary media configuration for tenants
- Site-specific configuration through configuration records (see Configuration Management API)

## Authentication & Authorization

All endpoints require authentication via JWT bearer tokens. Most operations require the `NoChannelPortalAccess` security scheme, indicating administrative access.

Many endpoints also require the `x-upstart-tenant` header to specify which tenant context the operation applies to. This ensures operations are scoped correctly in the multi-tenant environment.

### Required Permissions

Operations document their required permissions (e.g., `tenant.create`, `tenant.read`, `tenant.update`, `tenant.delete`). Ensure your access token includes the necessary permissions for the operations you need to perform.

## Getting Started

To get started with the Tenant API:

1. **Obtain Authentication**: Get a JWT token with appropriate permissions
2. **Create Your First Tenant**: Use `POST /v1/tenants/create` with tenant details and at least one site
3. **Verify the Tenant**: Complete email verification using the verification code
4. **Retrieve Tenant Details**: Use `GET /v1/tenants/{tenantId}` to see complete tenant configuration
5. **Manage Sites**: Add, update, or configure sites as needed

Refer to the endpoint documentation below for detailed request/response schemas, examples, and error handling.