Multi-tenancy

ScaiWave is multi-tenant at every layer. There is no "global" data — every row in every table carries a tenant_id, every API request resolves to a single tenant, every Redis key is namespaced, every queue job carries the tenant in its payload.

What a tenant is#

A tenant is an isolated organisation: a company, a team, a project. Tenants get:

• A unique slug and a friendly name.
• A scaikey_tenant_id — the same tenant, identified to the identity provider.
• Optional partner_id — for partner-managed tenants under a parent organisation.
• Limits (max participants, max rooms, max storage, AI tokens monthly).
• A features JSON for per-tenant feature flags (prompt_studio.enabled, sidekick_limits.max_concurrent, etc.).
• Configurable AI defaults (enabled models, default model, system prompt templates, ScaiGrid auth mode, ScaiGrid API key when in per-user mode).

Resolution#

Every request flows through middleware (TenantMiddleware) that:

1. Reads the bearer token.
2. Resolves the principal's tenant_id from the ScaiKey JWT claim.
3. Loads the tenant row + its limits and features.
4. Attaches a TenantContext (frozen dataclass) to request.state.

Every service constructor downstream takes that TenantContext. There is no global "current tenant" — everything is parameter-passed, so cross-tenant leakage requires a deliberate bug, not just forgetting.

Database scoping#

Every query that returns user data filters on tenant_id. SQLAlchemy sessions don't enforce this — the convention is enforced by code review and the service layer being the only path to mutations.

There is no row-level security in the database; tenants are not strongly isolated at the storage level. If you need that, you'd run separate ScaiWave instances per tenant, with their own DBs.

Redis scoping#

Every Redis key uses the pattern sw:{tenant_id}:{namespace}:{key}, e.g. sw:abc-123:presence:user-xyz, sw:abc-123:sidekick_token:task-456. Cross-tenant key collisions are impossible.

NATS scoping#

JetStream subjects are tenant-scoped via the room id (which is tenant-scoped). Consumers can subscribe to swp.room.*.> patterns without seeing cross-tenant events.

Partners#

A partner is an organisation that operates a fleet of tenants on behalf of clients. Partners get their own admin API surface (/v1/admin/partners/*) and partner-scoped views. A tenant's partner_id (nullable) records the parent.

This is meaningful for billing, support, and the "manage tenants on behalf of customers" workflow.

Quotas and limits#

Most can be overridden per tenant by an admin.

When tenants talk to each other#

Two ways:

• Federation — symmetric, signed protocol; a foreign participant joins your room as a real member. See Federation.
• Bridges — asymmetric webhook protocol; a foreign system relays messages in and out via signed HTTP. See Bridges.

Neither breaks tenant isolation. Federated events are stored in your DB as tenant_id = <your-tenant>, with a foreign_origin flag.

Where to go next#

• Federation.
• Bridges.
• API: Admin.
• Reference: Configuration.