Multi-Tenancy Architecture

ValidonX uses a database-per-tenant isolation model. Each tenant gets a dedicated MySQL database containing their licenses, activations, entitlements, and usage data. The platform database stores shared data: tenants, users, subscriptions, billing, and audit logs.

How It Works

┌─────────────────────────────────────┐
│         Platform Database           │
│  (validonx_platform)                │
│                                     │
│  tenants, users, admins, plans,     │
│  subscriptions, invoices, api_keys, │
│  audit_logs, webhook_endpoints      │
└─────────────────────────────────────┘
          │
          │ tenant_id foreign key
          │
    ┌─────┴─────┬──────────────┐
    ▼           ▼              ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Tenant A │ │ Tenant B │ │ Tenant C │
│ (vx_     │ │ (vx_     │ │ (vx_     │
│ tenant_  │ │ tenant_  │ │ tenant_  │
│ acme)    │ │ beta)    │ │ corp)    │
│          │ │          │ │          │
│ licenses │ │ licenses │ │ licenses │
│ activ.   │ │ activ.   │ │ activ.   │
│ entitl.  │ │ entitl.  │ │ entitl.  │
│ usage    │ │ usage    │ │ usage    │
└──────────┘ └──────────┘ └──────────┘

Tenant Resolution

Every API request is routed to the correct tenant database via middleware:

• Integration API (/v1/integration/*): Resolved from X-API-Key header. The API key hash is looked up in the platform database to find the tenant.
• Tenant API (/v1/tenant/*): Resolved from the authenticated user's Sanctum token. If a user belongs to multiple tenants, the X-Tenant-ID header selects which one.

Provisioning

New tenants go through a 12-stage idempotent pipeline:

1. Validate tenant record
2. Create isolated database
3. Run tenant migrations
4. Seed configuration defaults
5. Initialize subscription (plan-linked)
6. Initialize entitlements (plan-specific)
7. Initialize usage counters
8. Set branding defaults
9. Generate API key (HMAC-SHA256 hashed)
10. Create webhook endpoint placeholder
11. Emit audit event
12. Health check and status → active

Data Isolation Guarantees

• Each tenant's data is in a separate database — no shared tables
• Database connection is switched per-request via TenantDatabaseManager
• API keys are scoped to a single tenant
• Rate limits are enforced per-tenant and per-API-key
• Audit logs include tenant_id for correlation