Tenant Endpoints

The tenant endpoints manage the core tenant lifecycle, including creation, retrieval, updates, tier upgrades, suspension, activation, and deletion. Served by TenantController at /api/v1/tenants.

Endpoints

Method	Endpoint	Description
POST	`/api/v1/tenants`	Create tenant and start provisioning
GET	`/api/v1/tenants`	List tenants (paginated, filterable)
GET	`/api/v1/tenants/:id`	Get tenant by ID
GET	`/api/v1/tenants/slug/:slug`	Get tenant by slug
PUT	`/api/v1/tenants/:id`	Update tenant properties
POST	`/api/v1/tenants/:id/upgrade`	Upgrade tenant tier
POST	`/api/v1/tenants/:id/suspend`	Suspend tenant access
POST	`/api/v1/tenants/:id/activate`	Reactivate suspended tenant
DELETE	`/api/v1/tenants/:id`	Soft delete tenant
GET	`/api/v1/tenants/:id/resources`	Get provisioned resources
GET	`/api/v1/tenants/stats`	Get tenant statistics

POST /api/v1/tenants

Creates a new tenant and initiates asynchronous provisioning. Returns the tenant record immediately while provisioning runs in the background.

{
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "tier": "PROFESSIONAL",
  "adminEmail": "admin@acme.com",
  "region": "us-east-1",
  "settings": {
    "maxUsers": 100,
    "dataRetentionDays": 365
  }
}

Status	Description
201	Tenant created, provisioning started
400	Invalid request
409	Tenant with slug already exists

GET /api/v1/tenants

Returns a paginated list of tenants with filtering and search.

Parameter	Type	Default	Description
`page`	int	0	Page number
`size`	int	20	Page size
`sortBy`	string	`createdAt`	Sort field
`sortDir`	string	`desc`	Sort direction (`asc` or `desc`)
`status`	enum	--	Filter by status (ACTIVE, SUSPENDED, etc.)
`search`	string	--	Search by name or slug

Tenant Tier Upgrade

POST /api/v1/tenants/:id/upgrade

{
  "newTier": "ENTERPRISE"
}

Supported tiers: FREE, STARTER, PROFESSIONAL, ENTERPRISE.

Suspend and Activate

Suspending a tenant disables all access. An optional reason can be provided.

POST /api/v1/tenants/:id/suspend?reason=Payment%20overdue
POST /api/v1/tenants/:id/activate

DELETE /api/v1/tenants/:id

Performs a soft delete. The tenant record is retained for audit purposes but all provisioned resources are scheduled for deprovisioning.

Overview Provisioning Endpoints