Multi-tenancy
NetForge ships with always-on multi-tenancy plumbing that stays invisible until you turn it on — single-tenant developers see no "tenant" anywhere. Flip it with one config setting:
"Tenancy": { "Mode": "MultiTenant" } // Resolution defaults to UserClaim — see below
What you get when it's on
- Tenant catalog —
/admin/tenants(host admins,tenants.*) lists, creates, and edits tenants; each has a name, status (Active/Suspended), brand colour, and logo. Those three white-label the shell for whoever is in that tenant — including the default one, which is your own product identity, so editing it rebrands the app itself. The default tenant can't be deleted. - Per-tenant roles — a user's roles are scoped to a tenant. The same person can be Admin in one tenant and a read-only member in another; permissions re-project the moment they switch. Role definitions are shared; the assignment is per-tenant.
- Tenant admins — Admin in a customer's tenant runs that tenant: its members, invitations, joining rules, appearance, webhooks, audit log and data. Platform-wide permissions (user accounts, role definitions, app settings, tenants, health, background jobs) only apply in the default tenant, so host administration happens there. From inside another tenant,
/admin/tenantsopens that tenant's own page and can't reach any other. Nobody can change their own roles. - Tenant switcher — a top-bar control lists the tenants you belong to; switching re-tints the app with that tenant's branding and reloads into its data. On a narrow phone it shows just its icon, and on the very narrowest it moves into the account menu.
- Invitations — invite someone by email to a tenant with a role; they get a signed link to an accept page. Pending invitations can be revoked.
- Who can join — a tenant is invitation-only until you say otherwise. Its page has two joining rules, each with its own role: people with an email at these domains (staff at
@acme.comjoin as Staff) and anyone (a community or public workspace, with a narrow role). People join when they confirm their email — that's what proves the address — and a domain match beats the open rule. It applies to sign-ups on the tenant's own address (Host/Subdomain/Path/Headerresolution). OAuth sign-ups can only use the open rule, and a role that grants every permission can't be handed out this way. - Isolation — every tenant-scoped record carries a
TenantIdand is filtered automatically, so one tenant never sees another's data.

Switching tenant re-skins the whole shell with that tenant's brand — same app, same account, a different identity over a completely isolated data set:


Resolution strategies
The active tenant always derives from the signed-in user, so a forged host, subdomain, or header can't reach a tenant you don't belong to — a request that names a different tenant from yours is refused. The strategy decides how an unauthenticated request (the sign-in page, its branding) is mapped:
| Strategy | Example | Best for |
|---|---|---|
| UserClaim (default) | from the signed-in user | one hostname for everyone — most apps |
| Host | portal.acme.com → acme, via HostMap | each customer on their own domain |
| Subdomain | acme.app.com | classic SaaS |
| Path | /acme/… | single-domain hosting |
| Header | X-Tenant-Id | API clients |
"Tenancy": {
"Mode": "MultiTenant",
"Resolution": "Host",
"HostMap": { "portal.acme.com": "acme", "app.globex.io": "globex" }
}A request can only name a tenant that exists: an unmapped host, or a subdomain label, path segment, or header that isn't a tenant's id, names none, and the request falls back to the signed-in user's tenant (or the default one). So demo.example.com on a single-tenant-per-host deployment doesn't invent a tenant called demo. Subdomain also checks HostMap first, so most customers can use acme.app.com while a few bring their own domain. The setting is validated at startup — a misspelt strategy, or Host with an empty map, stops the app from booting and says why.
Making a feature tenant-aware
Add the ITenantScoped marker to an entity and a global WHERE TenantId = current filter is applied automatically; new rows are stamped with the active tenant on save. That's the whole change — the switcher, invitations, and resolution are already wired. It composes with the normal Add a feature flow: add the marker and the platform does the rest.
Community edition
Multi-tenancy management is a Pro feature; the always-on single-tenant scaffolding stays in every edition. See Editions.