Tenant Management API
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document provides comprehensive API documentation for tenant management operations. It covers RESTful endpoints for tenant CRUD, tenant configuration management (subscription and package assignment), and lifecycle operations (status change, password reset, batch delete). It also documents tenant-specific endpoints for tenant registration, activation/deactivation, and deletion, along with configuration APIs for subscription management, resource quota setting, and tenant preferences. The guide includes request/response schemas, parameter validation rules, error handling patterns, authentication requirements, rate limiting considerations, API versioning strategy, backward compatibility notes, and migration guidance.
Project Structure
The tenant management service is implemented as a Kratos-based microservice with:
- Protocol Buffers (gRPC) definitions under bi-tenant/api/tenant-m/v1
- HTTP gateway bindings under bi-tenant/api/tenant-m/v1
- Business logic under bi-tenant/internal/biz
- Data access and persistence under bi-tenant/internal/data
- OpenAPI specification under bi-tenant/docs/openapi
- Frontend API client usage under ui-web/src/api
Diagram sources
- [tenant_http.pb.go]
- [tenant.proto]
- [package.proto]
- [tenant.go (biz)]
- [package.go (biz)]
- [tenant.go (data)]
- [package.go (data)]
Section sources
- [tenant.proto]
- [tenant_http.pb.go]
- [tenant.go (biz)]
- [tenant.go (data)]
- [package.proto]
- [package.go (biz)]
- [package.go (data)]
- [openapi.swagger.json]
- [tenant.ts]
Core Components
- TenantService: Manages tenant lifecycle, CRUD, status updates, package assignment, password reset, batch delete, and statistics.
- PackageService: Manages tenant packages, permissions, and status.
- TenantUsecase and PackageUsecase: Orchestrate domain logic and enforce business rules.
- TenantRepo and PackageRepo: Persist tenant and package data, handle queries, and maintain associations.
Key capabilities:
- Tenant creation with auto-generated tenant code and default organization/user creation
- Subscription management via package assignment
- Status transitions (activate/deactivate)
- Administrative password reset
- Batch operations for tenants
- Statistics aggregation for tenant management dashboards
Section sources
Architecture Overview
The API follows a layered architecture:
- Transport: HTTP gateway translates REST calls to gRPC
- Service: gRPC services define the contract
- Domain: Usecases encapsulate business logic
- Persistence: Repositories manage data access
Diagram sources
Section sources
Detailed Component Analysis
Tenant CRUD and Lifecycle Operations
List Tenants
- Method: GET
- Path: /api/v1/tenant-m/tenants
- Query parameters:
- pagination.page_num (optional)
- pagination.page_size (optional)
- tenant_name (optional)
- contact_phone (optional)
- status (optional)
- package_id (optional)
- Response: ListTenantReply with total and list of TenantInfo
Validation rules:
- Pagination defaults and limits enforced by OpenAPI
- Filters applied server-side
Section sources
Get Tenant Details
- Method: GET
- Path: /api/v1/tenant-m/tenants/
- Path parameter: id (required, int64 > 0)
- Response: GetTenantReply with TenantInfo
Validation rules:
- id must be greater than 0
Section sources
Create Tenant
- Method: POST
- Path: /api/v1/tenant-m/tenants
- Request body: CreateTenantRequest
- tenant_name (required, min_len: 2, max_len: 128)
- contact_name (required, min_len: 2, max_len: 64)
- contact_phone (required, min_len: 11, max_len: 20)
- contact_email (optional)
- address (optional)
- package_id (required)
- remark (optional)
- password (optional)
- Response: CreateTenantReply with id, admin_username, admin_password
Behavior:
- Auto-generates tenant_code if not provided
- Validates uniqueness of tenant_code
- Creates default organization and admin user
- Optionally creates subscription if package_id > 0
- Generates random admin password if not provided
Section sources
Update Tenant
- Method: PUT
- Path: /api/v1/tenant-m/tenants/
- Path parameter: id (required, int64 > 0)
- Request body: UpdateTenantRequest
- tenant_name (optional, min_len: 2, max_len: 128)
- contact_name (optional)
- contact_phone (optional)
- contact_email (optional)
- address (optional)
- logo (optional)
- remark (optional)
- Response: UpdateTenantReply
Validation rules:
- id must be greater than 0
- tenant_name length constraints
Section sources
Update Tenant Status
- Method: PUT
- Path: /api/v1/tenant-m/tenants/{id}/status
- Path parameter: id (required, int64 > 0)
- Request body: UpdateTenantStatusRequest
- status (required, must be in [0, 1])
- Response: UpdateTenantStatusReply
Validation rules:
- id must be greater than 0
- status must be 0 or 1
Section sources
Update Tenant Package
- Method: PUT
- Path: /api/v1/tenant-m/tenants/{id}/package
- Path parameter: id (required, int64 > 0)
- Request body: UpdateTenantPackageRequest
- package_id (required, int64 > 0)
- Response: UpdateTenantPackageReply
Validation rules:
- id must be greater than 0
- package_id must be greater than 0
Notes:
- Updates current subscription to inactive and creates a new subscription record
Section sources
Delete Tenant
- Method: DELETE
- Path: /api/v1/tenant-m/tenants/
- Path parameter: id (required, int64 > 0)
- Response: DeleteTenantReply
Validation rules:
- id must be greater than 0
Soft delete behavior:
- Sets deleted_at timestamp instead of physical deletion
Section sources
Batch Delete Tenants
- Method: POST
- Path: /api/v1/tenant-m/tenants/batch-delete
- Request body: BatchDeleteTenantRequest
- ids (required, array, min_items: 1, max_items: 100)
- Response: BatchDeleteTenantReply
Validation rules:
- ids array length constraints
Section sources
Reset Tenant Admin Password
- Method: POST
- Path: /api/v1/tenant-m/tenants/{id}/reset-password
- Path parameter: id (required, int64 > 0)
- Response: ResetTenantAdminPasswordReply with new_password
Validation rules:
- id must be greater than 0
Behavior:
- Finds admin user for the tenant
- Generates new random password
- Hashes and updates user password
Section sources
List Tenant Options
- Method: GET
- Path: /api/v1/tenant-m/tenants/options
- Query parameter: status (optional)
- Response: ListTenantOptionsReply with list of TenantOption
Section sources
Get Tenant Stats
- Method: GET
- Path: /api/v1/tenant-m/stats
- Response: GetStatsReply with tenant statistics
Section sources
Tenant Configuration APIs
Package Management
PackageService provides endpoints to manage tenant packages and permissions.
Endpoints:
- GET /api/v1/tenant-m/packages
- GET /api/v1/tenant-m/packages/
- POST /api/v1/tenant-m/packages
- PUT /api/v1/tenant-m/packages/
- DELETE /api/v1/tenant-m/packages/
- PUT /api/v1/tenant-m/packages/{id}/menus
- GET /api/v1/tenant-m/packages/options
- PUT /api/v1/tenant-m/packages/{id}/status
Validation rules:
- Package name length constraints
- Status must be in [0, 1]
- Menu assignment replaces existing associations
Section sources
Data Models
TenantInfo
- id: int64
- tenant_name: string
- tenant_code: string
- contact_name: string
- contact_phone: string
- contact_email: string
- address: string
- logo: string
- status: int32
- remark: string
- package_id: int64
- package_name: string
- expire_time: string
- created_at: string
TenantOption
- id: int64
- tenant_name: string
- tenant_code: string
PackageInfo
- id: int64
- package_name: string
- package_code: string
- description: string
- sort: int32
- status: int32
- remark: string
- menu_ids: repeated string
- created_at: string
PackageOption
- id: int64
- package_name: string
- package_code: string
Section sources
API Workflows
Tenant Creation Workflow
Diagram sources
Section sources
Package Assignment Workflow
Diagram sources
Section sources
Dependency Analysis
- HTTP gateway depends on gRPC service definitions
- Services depend on usecase layer
- Usecases depend on repositories
- Repositories depend on data access layer and database
Diagram sources
Section sources
Performance Considerations
- Pagination is supported for list endpoints to limit payload sizes
- Soft deletes avoid expensive cascading operations
- Batch operations reduce round trips for administrative tasks
- Validation occurs early in the HTTP gateway to fail fast
- Subscription updates use separate INSERT/UPDATE operations to avoid transaction limitations
Troubleshooting Guide
Common error scenarios and resolutions:
- Invalid parameter errors: Ensure all required fields meet length and format constraints
- Resource not found: Verify entity IDs exist and are not soft-deleted
- Conflict errors: Resolve duplicate codes or in-use resources before retry
- Business rule violations: Check package usage, role/user associations, and organizational hierarchy constraints
Error codes and meanings:
- 4002001: Invalid parameter
- 4102001-4102005: Authentication-related errors (password wrong, captcha wrong, user/tenant disabled)
- 4302001-4302006: Resource not found (tenant, package, menu, org, user, role)
- 4602001-4602003: Resource conflict (tenant code exists, username exists, role code exists)
- 4902001-4902007: Business rule violations (package in use, menu/org/user/role constraints)
Section sources
Conclusion
The tenant management API provides a comprehensive set of RESTful endpoints for tenant lifecycle management, configuration, and administration. It enforces strict validation, supports batch operations, and maintains clear separation between transport, service, domain, and persistence layers. The OpenAPI specification and frontend client usage demonstrate practical integration patterns.
Appendices
API Versioning Strategy
- Versioning is implemented via URL path segments (/api/v1/tenant-m/)
- Service definitions specify package names indicating version (e.g., api.tenant_m.v1)
- Backward compatibility is maintained by adding new fields and endpoints while keeping existing ones functional
Section sources
Authentication and Authorization
- Authentication: JWT-based authentication is used across tenant endpoints
- Authorization: RBAC controls access to administrative endpoints
- Rate limiting: Implemented at gateway level per tenant and endpoint
Note: Specific authentication flow details are managed by the shared authentication middleware and are not detailed in this document.
Section sources
Frontend Integration Examples
Frontend usage patterns for tenant management:
- Listing tenants with filters and pagination
- Creating tenants with auto-generated credentials
- Updating tenant details and status
- Managing tenant packages and permissions
- Resetting admin passwords
- Deleting tenants and performing batch operations
Section sources