igny8/master-docs/00-system/07-MULTITENANCY-ACCESS-REFERENCE.md

Multi-Tenancy & Access Reference (Current State)

Purpose

Authoritative map of tenant isolation, role access, and payment/API-key handling across the stack. Built from code as of Dec 2025.

Core Enforcement Points (backend)

• Middleware:
  • backend/igny8_core/auth/middleware.py (AccountContextMiddleware, ~L1-L220): resolves request.account from JWT/API key; blocks inactive/suspended accounts.
  • backend/igny8_core/middleware/request_id.py (~L1-L70): request ID (not tenancy).
  • backend/igny8_core/middleware/resource_tracker.py (~L1-L170): metrics (not tenancy).
• Base viewsets:
  • backend/igny8_core/api/base.py (AccountModelViewSet, ~L1-L240): filters by request.account; admin/developer/system overrides; sets account on create.
  • backend/igny8_core/api/base.py (SiteSectorModelViewSet, ~L238-L430): additionally filters by site/sector and user’s accessible sites (SiteUserAccess) unless admin/developer/system.
• Permissions:
  • backend/igny8_core/api/permissions.py:
    • IsAuthenticatedAndActive, HasTenantAccess (default in settings).
    • IsViewerOrAbove, IsEditorOrAbove, IsAdminOrOwner.
    • IsSystemAccountOrDeveloper (system/admin for integrations).
  • Module-specific permissions also appear in backend/igny8_core/auth/permissions.py (legacy IsOwnerOrAdmin, IsEditorOrAbove, IsViewerOrAbove, AccountPermission).
• Settings defaults:
  • backend/igny8_core/settings.py REST_FRAMEWORK DEFAULT_PERMISSION_CLASSES = IsAuthenticatedAndActive + HasTenantAccess.
  • Auth order: APIKeyAuthentication → JWTAuthentication → CSRFExemptSessionAuthentication → BasicAuth.
  • Throttling: DebugScopedRateThrottle bypasses throttles for authenticated users/system/debug.
• Models with enforced account/site/sector:
  • Base models AccountBaseModel, SiteSectorBaseModel in backend/igny8_core/auth/models.py (top of file).

Flow (text flowchart)

Request
  -> Middleware: AccountContextMiddleware sets request.account (JWT/API key), validates account status/plan
  -> DRF Auth: APIKey/JWT/Session
  -> Permissions: IsAuthenticatedAndActive + HasTenantAccess (+ role-specific)
  -> ViewSet:
       AccountModelViewSet filters by account
       SiteSectorModelViewSet filters by account + site/sector + SiteUserAccess
  -> Action-specific role checks (IsEditorOrAbove, IsAdminOrOwner, IsSystemAccountOrDeveloper)
  -> Business logic (services) + credit checks (billing)
  -> Response

Module Access (backend ViewSets & guards)

• Accounts/Users/Plans/Subscriptions:
  • auth/views.py: UsersViewSet, AccountsViewSet, SubscriptionsViewSet, SiteUserAccessViewSet (account-scoped via AccountModelViewSet + role guards).
  • Roles: owner/admin (or developer/system) can manage; others limited to self (UsersViewSet get_queryset).
• Sites/Sectors:
  • auth/views.py (SiteViewSet, Sector actions): SiteSectorModelViewSet enforces account + site/sector + SiteUserAccess; public slug read is AllowAny for active site slug only.
• Planner:
  • modules/planner/views.py (KeywordViewSet, ClusterViewSet, ContentIdeasViewSet) inherit SiteSectorModelViewSet; require site_id/sector_id; role: typically editor+ for writes.
• Writer:
  • modules/writer/views.py (TasksViewSet, ContentViewSet, ImagesViewSet, ContentTaxonomyViewSet) inherit SiteSectorModelViewSet; site/sector scoping; editor+ for writes.
• Automation:
  • business/automation/views.py (AutomationViewSet) inherits AccountModelViewSet/SiteSectorModelViewSet patterns; requires site_id for run/config; role: editor+ for mutate.
• System settings (non-integrations):
  • modules/system/views.py / settings_views.py: AccountModelViewSet; role usually admin/owner; authenticated + tenant required.
• Integrations (OpenAI/Runware API keys):
  • modules/system/integration_views.py: guarded by IsSystemAccountOrDeveloper (system account or developer only); tenant-scoped but effectively system-only for keys.
• Billing:
  • modules/billing/views.py: AccountModelViewSet; IsAdminOrOwner for credit transactions/payment methods; balance/usage requires auth + tenant.
• Payments/Payment Methods:
  • Payment methods: AccountPaymentMethodViewSet account-scoped; IsAuthenticated; default selection per account; admin/owner should manage.
  • Payments: PaymentViewSet account-scoped; IsAuthenticated; list/available_methods/manual payment for current account only.

Frontend Guards

• Route protection: ProtectedRoute (auth required, checks account/plan/payment methods), ModuleGuard (module enabled), AdminGuard (integration/admin pages only for system account or developer).
• Sidebar hides Integration for non-system/developer; admin section shown only for system/developer.

AI Key Resolution

• ai/ai_core.py _load_account_settings: tries tenant IntegrationSettings → system account IntegrationSettings (aws-admin/default-account/default) → Django settings (OPENAI_API_KEY, RUNWARE_API_KEY). All users run AI with shared keys if tenant keys absent.

Throttling

• api/throttles.py DebugScopedRateThrottle: bypass for authenticated users/system/debug; per-scope rates in settings.py. Prevents 429s for normal users.

Payment / Billing Workflow (happy path)

1. User authenticates (JWT) → request.account set.
2. Payment methods (account-scoped) fetched via /v1/billing/payment-methods/available/; admin/owner can CRUD /v1/billing/payment-methods/.
3. Invoices/Payments via billing endpoints (account-scoped; admin/owner).
4. Credits used via CreditService on AI/automation calls (backend).

Access Summary by Role (runtime enforcement)

• Viewer: read-only where viewsets allow IsViewerOrAbove; no writes.
• Editor: can write planner/writer/automation; cannot manage billing/integration.
• Admin/Owner: manage account/team/billing/payment methods; full module writes.
• Developer/System account: cross-tenant overrides in some base filters; integration settings and admin menus.

Key Files (with line bands)

• Middleware: auth/middleware.py (~L1-220)
• Base viewsets: api/base.py (~L1-430)
• Permissions: api/permissions.py (~L1-200), auth/permissions.py (~L1-120)
• Settings (REST/Throttle): settings.py (REST_FRAMEWORK block, ~L200-360)
• AI core key loading: ai/ai_core.py (~L1-120)
• Integration settings views: modules/system/integration_views.py (~L1-300 main guards; actions throughout)
• Planner views: modules/planner/views.py (all ViewSets inherit SiteSectorModelViewSet)
• Writer views: modules/writer/views.py
• Automation: business/automation/views.py, services/automation_service.py
• Billing: modules/billing/views.py, business/billing/services/credit_service.py
• Payment methods: modules/billing/views.py AccountPaymentMethodViewSet
• Frontend guards: src/components/auth/ProtectedRoute.tsx, src/components/auth/AdminGuard.tsx, src/components/common/ModuleGuard.tsx
• Sidebar gating: src/layout/AppSidebar.tsx

Open Items / Risks

• Ensure public endpoints explicitly override default permissions (e.g., auth register/login, site slug read).
• Validate all viewsets still inherit AccountModelViewSet/SiteSectorModelViewSet after future changes.
• Add automated tests for cross-tenant denial, role gates, plan limits, and integration access.***