Tenant Management
Tenant management covers the full CRUD lifecycle of tenant organizations within the MATIH platform. The TenantController at /api/v1/tenants provides paginated listing, search, creation, update, suspension, activation, and soft deletion of tenants.
Key Concepts
| Concept | Description |
|---|---|
| Tenant | An organization on the platform with isolated resources, users, and data |
| Slug | A unique, URL-safe identifier (3-63 chars, lowercase alphanumeric with hyphens) |
| Tier | Subscription level: FREE, STARTER, PROFESSIONAL, ENTERPRISE |
| Status | Lifecycle state: PENDING, PROVISIONING, ACTIVE, UPGRADING, SUSPENDED, FAILED, DELETED |
| Soft Delete | Tenants are never physically removed; they are marked deleted=true with a timestamp |
Controller Overview
The TenantController is mapped to /api/v1/tenants and provides the following operations:
@RestController
@RequestMapping("/api/v1/tenants")
@Tag(name = "Tenants", description = "Tenant management APIs")
public class TenantController {
private final TenantService tenantService;
private final ProvisioningService provisioningService;
private final TenantResourceRepository resourceRepository;
private final TenantMapper tenantMapper;
}Endpoints Summary
| Method | Path | Description |
|---|---|---|
POST | /api/v1/tenants | Create a new tenant |
GET | /api/v1/tenants | List tenants (paginated) |
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 |
POST | /api/v1/tenants/{id}/upgrade | Upgrade tenant tier |
POST | /api/v1/tenants/{id}/suspend | Suspend tenant |
POST | /api/v1/tenants/{id}/activate | Activate 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 |
Service Layer
The TenantService handles business logic with caching and transactional support:
- Caching: Tenant lookups are cached using
@Cacheable(value = "tenants")and evicted on mutations with@CacheEvict - Validation:
TenantValidationServicevalidates create and update requests - Duplicate Detection: Checks for duplicate slugs and admin emails before creation
- Tier Defaults: Automatically applies resource limits based on the selected tier
Sections
| Page | Description |
|---|---|
| Creating Tenants | Tenant creation flow, validation rules, and tier defaults |
| Updating Tenants | Updating properties and changing subscription plans |
| Tenant Status Lifecycle | Suspend, activate, and deletion workflows |
| Tenant Statistics | Platform-wide statistics and usage metrics |
| Self-Service Portal | Tenant settings, team invitations, and self-service features |