Tenancy And Role Model

Overlay currently uses a single-customer deployment model. That means the deployment boundary is the tenant boundary:

A self-hosted enterprise gets one web runtime, one Convex deployment, one object-store namespace, and one secret set.
A managed-cloud enterprise also gets one dedicated deployment and backend set.
Multiple stakeholders inside that enterprise are users with roles, not separate tenants.

Do not onboard multiple enterprise customers into the same Convex deployment with the current schema.

Tenants Versus Roles

A tenant is a hard data-isolation boundary. In today’s architecture, that boundary is the deployment itself. Roles are authorization rules inside one tenant. A school should normally be modeled like this:

Concept	Example
Tenant/deployment	Springfield School District
Roles	student, teacher, parent, administrator, IT administrator
Optional future grouping	school, classroom, grade, department, project, cohort

Do not add tenantId just to represent students, teachers, parents, departments, or classes. Future RBAC should use roles, groups, memberships, and policy checks within the same deployment.

Deployment Modes

Mode	Status	Tenant boundary
Self-hosted enterprise	Supported target	One customer per deployment.
Managed-cloud enterprise	Supported target	One customer per dedicated managed deployment.
Shared multi-tenant cloud	Not supported today	Multiple customers in one backend, blocked until tenant isolation is implemented.

The current config schema rejects capabilities.multiTenant=true. Admin/system surfaces should report single-customer deployment; no tenant switcher or tenant-admin UI should appear.

Current Security Model

Single-customer deployment:

No tenantId column is required in Convex tables.
User-owned rows are scoped by userId inside that deployment.
API keys belong to a user in the deployment.
Webhook subscriptions and deliveries belong to a user in the deployment.
Storage keys and generated URLs are scoped to the deployment’s object-store namespace and user checks.
Operational isolation comes from separate Convex deployments, object-store buckets or prefixes, secrets, domains, logs, and provider credentials.

This is the required model for enterprise customers until shared multi-tenant deployment support exists.

API Keys And Webhooks

API keys:

Current behavior: API keys are deployment-local and user-owned through apiKeys.userId.
No tenant claim is encoded or enforced because the deployment is the tenant boundary.
A dedicated managed-cloud enterprise must have its own API_KEY_HASH_SECRET.
Shared multi-tenant requirement: API keys must include tenant ownership, tenant-aware scopes, tenant-aware rate-limit keys, tenant-aware audit entries, and validation that the key tenant matches the request tenant.

Webhooks:

Current behavior: webhook subscriptions and deliveries are deployment-local and user-owned through webhookSubscriptions.userId and webhookDeliveries.userId.
No tenant routing field exists because the deployment is the tenant boundary.
Shared multi-tenant requirement: webhook subscriptions, deliveries, event ownership, signing secrets, retries, and delivery runner queries must include tenant context.

Convex Table Tenant Decisions

These user-owned tables intentionally do not have tenantId today because the deployment is the tenant boundary. npm run check:tenant-boundaries verifies that every current userId-owned Convex table is listed here.

Table	Current owner	Tenant decision	Shared multi-tenant requirement
`userUiSettings`	`userId`	Deployment boundary	Add `tenantId` to row and `by_tenantId_userId` indexes.
`subscriptions`	`userId`	Deployment boundary	Add `tenantId`; Stripe customer/subscription indexes must include tenant ownership.
`budgetTopUps`	`userId`	Deployment boundary	Add `tenantId`; payment/session indexes must validate tenant ownership.
`apiIdempotencyKeys`	`userId`	Deployment boundary	Add `tenantId`; idempotency keys must be tenant-scoped.
`apiKeys`	`userId`	Deployment boundary	Add `tenantId`; validation, scopes, rotation, revocation, audit, and rate limits must enforce tenant context.
`tokenUsage`	`userId`	Deployment boundary	Add `tenantId`; usage and billing rollups must be tenant-scoped.
`budgetReservations`	`userId`	Deployment boundary	Add `tenantId`; reservation and reconciliation queries must be tenant-scoped.
`daytonaWorkspaces`	`userId`	Deployment boundary	Add `tenantId`; sandbox lifecycle and metering indexes must include tenant context.
`daytonaUsageLedger`	`userId`	Deployment boundary	Add `tenantId`; ledger reads and reconciliation must be tenant-scoped.
`toolInvocations`	`userId`	Deployment boundary	Add `tenantId`; audit/cost views must include tenant context.
`dailyUsage`	`userId`	Deployment boundary	Add `tenantId`; usage counters must include tenant context.
`projects`	`userId`	Deployment boundary	Add `tenantId`; project hierarchy indexes must include tenant context.
`skills`	`userId`	Deployment boundary	Add `tenantId`; project and enabled-skill indexes must include tenant context.
`automations`	`userId`	Deployment boundary	Add `tenantId`; scheduling and runner queries must not cross tenants.
`automationRuns`	`userId`	Deployment boundary	Add `tenantId`; run history and scheduler claims must be tenant-scoped.
`mcpServers`	`userId`	Deployment boundary	Add `tenantId`; connector credentials and enabled indexes must be tenant-scoped.
`conversations`	`userId`	Deployment boundary	Add `tenantId`; share tokens need explicit cross-tenant policy.
`conversationMessages`	`userId`	Deployment boundary	Add `tenantId`; conversation/message indexes must include tenant context.
`conversationMessageDeltas`	`userId`	Deployment boundary	Add `tenantId`; streaming/delta cleanup queries must include tenant context.
`conversationContextSummaries`	`userId`	Deployment boundary	Add `tenantId`; context summary indexes must include tenant context.
`notes`	`userId`	Deployment boundary	Add `tenantId`; note/project indexes must include tenant context.
`memories`	`userId`	Deployment boundary	Add `tenantId`; memory extraction and search must enforce tenant context.
`knowledgeChunks`	`userId`	Deployment boundary	Add `tenantId`; search indexes must include `tenantId` as a filter field.
`knowledgeChunkEmbeddings`	`userId`	Deployment boundary	Add `tenantId`; vector indexes must include `tenantId` as a filter field.
`outputs`	`userId`	Deployment boundary	Add `tenantId`; generated output and storage ownership must be tenant-scoped.
`r2UploadIntents`	`userId`	Deployment boundary	Add `tenantId`; upload finalization must include tenant context.
`files`	`userId`	Deployment boundary	Add `tenantId`; file/folder/share indexes must define cross-tenant behavior.
`webhookSubscriptions`	`userId`	Deployment boundary	Add `tenantId`; subscriptions, signing secrets, and event ownership must be tenant-scoped.
`webhookDeliveries`	`userId`	Deployment boundary	Add `tenantId`; delivery runner claims and retries must enforce tenant ownership.

The following tables are not user-owned tenant data today. They still need review before shared multi-tenant deployments, but the static check only requires explicit documentation for userId-owned tables:

processedWebhookEvents
rateLimitWindows
serviceAuthReplayNonces
sessionTransferTokens

Shared Multi-Tenant Checklist

Do not enable shared multi-tenant deployments until this checklist is complete:

Schema migration plan for adding tenantId to every user-owned table.
Backfill plan for existing rows.
Index expansion plan for every secondary, search, and vector index.
Tenant-aware auth/session claims.
Tenant-aware role and membership model.
Tenant-aware API keys, scopes, audit trail, and per-key/per-tenant rate limits.
Tenant-aware webhook subscription, delivery, retry, and signing-secret ownership.
Tenant-aware object-storage key namespace and public/share URL policy.
Cross-tenant negative tests for every domain service before enabling shared deployments.
UI policy for tenant switchers, unavailable states, and tenant admin surfaces.

Until then, use one deployment per enterprise customer.

​Tenants Versus Roles

​Deployment Modes

​Current Security Model

​API Keys And Webhooks

​Convex Table Tenant Decisions

​Shared Multi-Tenant Checklist