Multi-tenancy: concepts & vocabulary

Part of the Multi-tenancy section. Planned / in design.

Getting a handful of words straight up front is what stops multi-tenancy getting confusing. Keep this page handy.

The core words

Term	What it means
Tenant (a.k.a. company / client)	A separate client company. This is the isolation boundary — one tenant can never see another's data. Acme Ltd, Globex, "the biscuit factory".
Department	A team inside one company — IT, Finance, HR. A department is not a tenant; it lives within a company.
Analyst	A member of your support staff. Analysts can legitimately work across companies (handling Acme in the morning, Globex in the afternoon) — subject to permissions.
Requester	An end user who raises tickets (by email or via the self-service portal).
Mailbox	A connected email account that FreeITSM both reads from and sends as. A mailbox is the email identity of a company (or a department).

The one distinction that matters most: company vs department

This trips people up, so it's worth nailing:

• A company (tenant) is a separate organisation. Acme and Globex are two companies.
• A department is a team inside one organisation. Acme's IT team and Acme's Finance team are two departments of one company.

A common mistake is to reach for a new company when you really want a new department. Rule of thumb:

Different organisation → new company. Same organisation, different team → new department.

If a single business buys another business and wants their service desks kept apart, that's genuinely two companies. If a business simply adds its Finance team to the same service desk, that's a second department of one company.

Two kinds of people, two different rules

The whole design hangs off the fact that the two groups of people behave differently:

• Analysts (your staff) are cross-company operators. They move between clients, and the interface gives them a company switcher and an "all companies" view for searching.
• Requesters (end users) are a single global identity whose individual tickets each belong to one company. One person, one login — but each ticket they raise is filed under the right client. See Users & self-service.

That asymmetry — staff roam, end-user tickets stay put — is why the staff and portal experiences are designed quite differently.

Writing code? tenant_id has three meanings

This page is the vocabulary. The one thing it deliberately does not cover is what an empty tenant_id means in the database, because the answer depends on which kind of table you are looking at:

Kind of table	Example	NULL means
Scoped data	tickets, assets, tasks	the Default company's (unrouted or pre-migration)
Config list	ticket_types, canned responses	a global default, everyone sees it
Connection	mailboxes, messaging channels, issue-tracker connections	shared intake, serves every company

Two of those are opposites, and reaching for the wrong one hides rows rather than erroring — so the mistake is silent.

The rules, the filters to use for each, and the checklist are in the Multi-Tenancy Developer Guide. Read it before scoping any table. Several pages used to send readers here for that answer, which is not something this page has ever explained.