Multi-tenancy
How Finance Operating System isolates organisations at the database, API, and UI layers.
Multi-tenancy
Finance Operating System is a multi-tenant SaaS: many organisations share the same database, same servers, same code. We isolate them rigorously, but understanding how the isolation works helps you debug auth issues, build correct integrations, and reason about security.
The model
Every domain table — Invoice, Bill, Contact, BankTransaction, etc. — has a tenantId column that points at an Organization. The organisation is the tenant. Users do not directly own data; they belong to one or more organisations via Member rows, and they can switch the "active organisation" in the UI to see different sets of books.
A user can be a member of many organisations (an accountant typically is a member of every client). The Session.activeOrganizationId field tracks which organisation the current session is currently looking at. Every query the application makes filters by that organisation.
Enforcement layers
The isolation is enforced at three layers, defence-in-depth:
- Prisma extension. Every query through the shared
prismainstance is wrapped by an extension that injectswhere: { tenantId: <activeOrgId> }and overridesdata: { tenantId: <activeOrgId> }on writes. A query missing a tenantId filter on a tenant-scoped table throws at runtime. Seepackages/db/src/tenant-extension.ts. - API route guards. Every API route resolves the session, derives the active organisation, and asserts the actor is a member with the required role. Requests without a valid session return
401; requests with a session but no membership for the targeted organisation return403. - Database-level constraint scans. Nightly, we run a job that samples 10,000 random rows from each tenant-scoped table and verifies the
tenantIdmatches the access-pattern envelope (e.g. an Invoice's contactId points at a Contact in the same tenant). Mismatches page on-call.
What this means for integrations
API keys are scoped to a specific organisation. You cannot list, say, contacts across all organisations the underlying user belongs to — there is no "global me" endpoint. If your integration needs to drive multiple organisations (e.g. an accountant's tool), generate one key per organisation.
The tenantId is never exposed in responses (since it is implicit — every key is one-tenant). It is included on webhook payloads as event.tenantId so multi-tenant consumers can route.
Migrating data between organisations
There is no "move this invoice to another organisation" feature. Each organisation is logically isolated; moving data between them is a re-import, not a transfer. If you need to merge two organisations (acquisition, restructure), contact support — we can do this manually, with auditing.
Performance
The tenantId is the leading column of every multi-column index we have. PostgreSQL's planner uses it to partition prune at every query — a query for one tenant never touches another tenant's pages on disk in normal operation. Larger tenants get isolated read replicas; if your books exceed ~10M journal lines, the auto-routing layer points your reads at the dedicated replica.

