Multi-tenancy
What it is
The system is designed so that several companies share one deployment without their data mixing. Each company is a "tenant" — a fully separate workspace.
→ See also Roles and permissions and Company ownership lifecycle.
How data is separated
When a user signs in, the JWT carries the company chosen for that session. Before returning tenant-scoped data, the server checks that the user still has an active membership in that company and applies that membership's role and grants. The company in the token does not replace that check.
Ana signs in to Acme Corp
│
▼
Token: { userId: "...", companyId: "acme-uuid", role: "admin" }
│
▼
GET /v1/users → only Acme Corp usersSwitching company within one session
If Ana belongs to two companies, the session can select any of her active memberships. X-Company-Id only changes the context after that membership is verified; without a membership the server rejects the request. The same applies to a user who is also a Super Admin.
The X-Company-Id header does not grant access
For a user JWT, the requested company must have an active UserCompany membership for that user. Otherwise the request is rejected; isSuperAdmin does not allow selecting a company the user does not belong to. When the header is absent, the companyId in the JWT still requires an active membership.
An app client (tokenType: app) uses its own scope: it can only select a company linked to the client. API keys stay bound to their company and do not use the header to widen their scope.
Single-company vs multi-company mode
| Mode | Setting | Behaviour |
|---|---|---|
| Single company (default) | multi_company = false | Each user can belong to one company only |
| Multi-company | multi_company = true | A user can be a member of several companies with own roles |
It is switched at runtime from the platform settings without restarting the server.