Tenants Module

Overview

Multi-tenancy is the architectural foundation of ThreatOps SOCaaS. Every alert, incident, detection rule, SLA record, and user is scoped to a tenant. Without a robust tenant management layer, a platform operator cannot onboard new customers, control their tier and SIEM configuration, or enforce isolation between organizations.

The Tenants module provides the data layer and API for creating, listing, reading, and updating tenant records. It enforces role-based access control — super admins see all tenants, while standard users see only their own tenant. A graceful fallback to realistic demo data ensures the frontend remains functional even when the database is unavailable. Tenant creation is integrated with the onboarding flow, allowing new tenants to be added directly from the UI.

What Was Proposed

• Full CRUD API for tenant records (create, list, get, update)
• Role-based access control: super admins see all tenants, non-super-admins see only their own
• Tenant attributes: name, slug, tier (standard/premium/enterprise), primary SIEM, status, endpoint count, settings, and subscription dates
• Graceful fallback to demo data when the database is unavailable
• Frontend management table with tier and status color-coding, onboarding progress bars, and navigation to the onboarding flow
• Integration with tenant middleware for request-scoped tenant ID injection

What's Built

Architecture

Backend Router

File: app/routers/tenants.py — Prefix: /api/v1/tenants

The router uses async SQLAlchemy with AsyncSession injected via Depends(get_db). All queries use select(Tenant) with await db.execute(). A _demo_tenants() helper returns three pre-configured realistic tenants (Acme Financial Corp, GlobalHealth Systems, TechStart Inc) as a JSONResponse when any database exception is raised, allowing the frontend to function during development or database outages.

Role-Based Access Control

The list endpoint checks request.state.user_role (injected by the tenant middleware) against the value "super_admin". Super admins receive an unfiltered query over all tenant rows. All other roles receive a query filtered to Tenant.id == request.state.tenant_id, ensuring strict tenant isolation. The get-by-ID endpoint enforces the same check with an explicit 403 response rather than filtering.

Data Flow

Browser (Next.js)
  --> GET /api/v1/tenants/
  --> TenantMiddleware sets request.state.tenant_id + user_role
  --> tenants router: if user_role != "super_admin": filter by tenant_id
  --> SQLAlchemy async query against PostgreSQL `tenants` table
  --> On DB error: return _demo_tenants() as JSONResponse
  --> Frontend renders table with tier/status badges + progress bars

Tenant Middleware

File: app/middleware/tenant.py — Inspects the JWT bearer token on every request and sets request.state.tenant_id and request.state.user_role. These values are consumed by the tenants router, alerts router, incidents router, and all other tenant-scoped modules.

Frontend Page

File: src/app/tenants/page.tsx — Client component that calls getTenants() from src/lib/api.ts on mount. Falls back silently to five hardcoded demo tenants (California Dept of Technology, Acme Corp, City of Merced, Fresno COE, San Mateo County) if the API call throws. The page uses Next.js useRouter for programmatic navigation to /onboarding?tenant={slug} on row click and to /onboarding on the Add Tenant button.

API Endpoints

GET    /api/v1/tenants/
       # List tenants. super_admin sees all; others see only their own tenant.
       # Query params: skip=0 (int), limit=50 (int)
       # Returns: list[TenantResponse]
       # Fallback: JSONResponse with 3 demo tenants on DB error

GET    /api/v1/tenants/{tenant_id}
       # Get a single tenant by ID.
       # 403 if non-super-admin requests a different tenant's record.
       # 404 if tenant does not exist.
       # Returns: TenantResponse

POST   /api/v1/tenants/
       # Create a new tenant.
       # Body: TenantCreate { name, slug, tier?, primary_siem, status?, settings?, ... }
       # Returns: TenantResponse (HTTP 201)

PATCH  /api/v1/tenants/{tenant_id}
       # Partial update of a tenant record.
       # Body: TenantUpdate { any subset of Tenant fields }
       # 404 if tenant does not exist.
       # Returns: TenantResponse

Routing

Data Model

Model: app/models/tenant.py — Table: tenants (SQLAlchemy declarative base)

Relationships

• users — One-to-many relationship with User model. Loaded with lazy="selectin" (automatic join on load).
• All alert, incident, detection rule, and SLA records have a tenant_id foreign key pointing to this table for multi-tenant isolation.

Demo Data (returned on DB failure)

Frontend Fallback Data

The frontend also has its own hardcoded fallback array displayed when the API call fails. This is a separate list from the backend demo data:

Prerequisites

• Database — PostgreSQL with async SQLAlchemy (app/core/database.py). The tenants table must exist. Alembic migrations create it. On failure, the router falls back to demo data.
• Tenant Middleware — app/middleware/tenant.py must be registered in app/main.py to inject request.state.tenant_id and request.state.user_role. Without it, the RBAC check in the list endpoint will raise an AttributeError.
• Auth Schemas — app/schemas/tenant.py defines TenantCreate, TenantUpdate, and TenantResponse Pydantic models used for request validation and response serialization.
• Frontend API helper — src/lib/api.ts exports the getTenants() function called by the page component. Uses the base API client with bearer token auth.

UI Layout