Multi-tenancy and isolation

SEMANTIX is built to host many independent customers in one deployment, and the isolation model is structural rather than a filter applied at query time.

The model

Schema per tenant. Each tenant gets its own PostgreSQL schema. Operational data does not share rows with another tenant’s.

Domain per tenant. Each tenant signs up on its own subdomain, e.g. acme.semantixapp.com. The domain determines which schema a request resolves to.

A token is bound to its tenant. An access token minted for tenant A is rejected when presented against tenant B. This is checked explicitly on every authenticated request, so a leaked or reused token cannot cross the boundary even if a request is somehow routed to the wrong schema.

Connections are pinned per request. A request’s database session is pinned to a single connection carrying that tenant’s search path, so a pooled connection cannot hand a request a view of another tenant’s data.

Access inside a tenant

Tenant isolation is the outer boundary. Within a tenant, access is shaped by context scopes and roles:

• Roles separate admins from analysts. Provider and connector configuration, trust assignment, and user management are admin-only.
• Scope grants decide which parts of the Registry a person can reach. A person with no granted scope sees an empty product.
• Primary scope sets the default context for Chat and the default board.
• Connector visibility is per data source: all exposes it to analysts, admins restricts it to admins.

Why the structural approach

Applying a tenant_id filter to every query is simpler to implement and easier to get wrong. A single forgotten predicate leaks another customer’s rows, and it usually leaks silently. Schema-per-tenant makes the mistake unavailable: the table is not in the search path, so the query fails rather than returning someone else’s data.

The cost is more schemas and a routing layer, which is a reasonable trade for making cross-tenant access structurally impossible rather than merely unlikely.

Self-hosting

A self-hosted deployment keeps the same model — the tenancy layer is part of the application, not a hosted-service feature. Running your own instance means your operational data and your data sources stay inside your infrastructure; see the deployment documentation for the topology.