🏢 Organization Management APIs
Multi-tenant SaaS organization lifecycle management
Executive Summary
Organization Management APIs control the full lifecycle of tenant organizations in the multi-tenant SaaS platform. SuperAdmins can create, configure, monitor, and suspend organizations across the platform.
✅ Full CRUD
Create, read, update, delete organizations
Create, read, update, delete organizations
✅ Bulk Operations
Mass update status, export data
Mass update status, export data
✅ API Keys
Organization-scoped API key management
Organization-scoped API key management
⚠️ Soft Delete Only
No hard delete for compliance
No hard delete for compliance
📊 API Inventory
| Controller | Route | Endpoints | Authorization | Key Features |
|---|---|---|---|---|
| AdminOrganizationController | /api/adminorganization | 12 | SuperAdmin+Admin | Full lifecycle management |
| SuperAdminDashboardController | /api/superadmindashboard | 1 | SuperAdmin only | Platform overview |
🔄 Organization Lifecycle
Organization Lifecycle State Machine
═══════════════════════════════════════════════════════════════════════════════
┌─────────────┐
│ PENDING │
│ (Created) │
└──────┬──────┘
│
│ Activate
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ SUSPENDED │◄────────────│ ACTIVE │────────────►│ EXPIRED │
│ (Violation) │ Suspend │ (Normal) │ Trial End │ (Payment) │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ Reactivate │ Deactivate │ Renew
└────────────────────────────┘ │
│ ▼
│ ┌─────────────┐
│ │ ARCHIVED │
└──────────────────►│ (Read-only)│
└─────────────┘
Status Transitions API:
───────────────────────────────────────────────────────────────────────────────
POST /api/adminorganization/{id}/status
Body: { "status": "Active|Inactive|Suspended|Expired", "reason": "..." }
Authorization:
• SuperAdmin: Can transition any org to any state
• Admin: Can only deactivate own org (with approval workflow)
🔌 Key Endpoints
Organization CRUD
POST
/api/adminorganization
Create new organization. Auto-generates API key and default settings.
SuperAdmin only Existing
{
"name": "Acme Corp",
"planId": "pro-plan-guid",
"adminEmail": "admin@acme.com",
"settings": { "maxUsers": 100, "features": ["analytics", "exports"] }
}
GET
/api/adminorganization/{id}
Get organization details including settings, subscription, usage stats.
SuperAdmin+Admin Existing
PUT
/api/adminorganization/{id}
Update organization name, settings, configuration.
SuperAdmin+Admin Existing
DELETE
/api/adminorganization/{id}
Soft delete organization (sets IsDeleted=true, retains data for compliance).
SuperAdmin only Existing
Search & Bulk Operations
GET
/api/adminorganization/search
Search organizations by name, status, plan, creation date. Supports pagination.
SuperAdmin only Existing
Query: ?query=acme&status=Active&planId=...&page=1&pageSize=20
POST
/api/adminorganization/bulk
Bulk operations: update status, regenerate API keys, export data.
SuperAdmin only Existing
API Key Management
POST
/api/adminorganization/{id}/apikey
Regenerate organization API key. Old key invalidated immediately.
SuperAdmin+Admin Existing
⚖️ Multi-Tenant Governance
Multi-Tenant Data Isolation Architecture
═══════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────┐
│ SHARED INFRASTRUCTURE │
│ (Single Database, Multiple Tenants) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Organizations Table │ │
│ │ ┌─────────┬──────────────┬──────────┬─────────────┬───────────────┐ │ │
│ │ │ Id │ Name │ Status │ ApiKey │ PlanId │ │ │
│ │ ├─────────┼──────────────┼──────────┼─────────────┼───────────────┤ │ │
│ │ │ org-001 │ Acme Corp │ Active │ ak_live_xxx │ pro-plan │ │ │
│ │ │ org-002 │ TechStart Inc│ Active │ ak_live_yyy │ basic-plan │ │ │
│ │ │ org-003 │ GlobalCo │Suspended│ ak_live_zzz │ enterprise │ │ │
│ │ └─────────┴──────────────┴──────────┴─────────────┴───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Users Table (Tenant-Scoped) │ │
│ │ ┌─────────┬──────────────┬─────────────┬─────────────────────────┐ │ │
│ │ │ Id │ Email │ OrgId (FK) │ Role │ │ │
│ │ ├─────────┼──────────────┼─────────────┼─────────────────────────┤ │ │
│ │ │ usr-101 │ john@acme.com│ org-001 │ Admin │ │ │
│ │ │ usr-102 │ jane@acme.com│ org-001 │ User │ │ │
│ │ │ usr-201 │ bob@tech.com │ org-002 │ Admin │ │ │
│ │ └─────────┴──────────────┴─────────────┴─────────────────────────┘ │ │
│ │ │ │
│ │ ⚠ CRITICAL: Every query MUST include: WHERE OrganizationId = @orgId │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Sessions Table (Tenant-Scoped) │ │
│ │ ┌─────────┬──────────────┬─────────────┬───────────┬───────────────┐ │ │
│ │ │ Id │ UserId │ OrgId │ StartTime │ AIUsageTime │ │ │
│ │ ├─────────┼──────────────┼─────────────┼───────────┼───────────────┤ │ │
│ │ │ ses-001 │ usr-101 │ org-001 │ 2026-01-15│ 02:34:00 │ │ │
│ │ │ ses-002 │ usr-102 │ org-001 │ 2026-01-15│ 01:12:00 │ │ │
│ │ │ ses-003 │ usr-201 │ org-002 │ 2026-01-15│ 00:45:00 │ │ │
│ │ └─────────┴──────────────┴─────────────┴───────────┴───────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ Tenant Isolation Enforcement: │
│ ├── MultiTenantIsolationMiddleware extracts OrgId from JWT │
│ ├── Validates Organization exists and is Active │
│ ├── Attaches X-Tenant-Id header to all responses │
│ └── Repository layer auto-filters by OrganizationId │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🗄️ Database Schema
| Table | Key Columns | Indexes | Relationships |
|---|---|---|---|
| Organizations | Id, Name, Status, ApiKey, PlanId, Settings, CreatedAt | PK Id, IX ApiKey (unique), IX Status | 1:N Users, Sessions, Devices |
| OrganizationSettings | OrgId, Key, Value | PK (OrgId, Key) | N:1 Organizations |
| Subscriptions | Id, OrgId, PlanId, Status, StartDate, EndDate | PK Id, IX OrgId | N:1 Organizations, Plans |
| Plans | Id, Name, Features, Limits, Price | PK Id | 1:N Subscriptions |
⚠️ Security & Compliance Notes
Soft Delete Only
Organizations marked as deleted retain data for GDPR/SOC2 compliance. Hard delete requires manual DB intervention.
Audit Trail
All organization changes logged to AuditLogs table with before/after state.
API Key Rotation
No automatic key rotation policy. Manual regeneration only. Recommend 90-day rotation.
Data Export
Full org data export available but may be slow for large orgs. Background job recommended.
✅ Recommended Future Enhancements
Organization Templates
Pre-configured templates for common org types (Enterprise, SMB, Startup).
Recommended
Sandbox Orgs
Isolated sandbox organizations for testing without affecting production data.
Recommended
Org-to-Org Migration
Transfer users/data between organizations (mergers, acquisitions).
Recommended