Multi-tenancy
@basaltkit/tenancy makes every request tenant-aware: a resolver identifies the tenant from the incoming request, a TenantSource loads its record, and the result lives in the request context — where cache, storage, queue, logger and your Prisma client pick it up automatically. It is decoupled from auth and teams: resolving a tenant answers which tenant a request is about, never whether the caller may act on it.
Mental model
Four pieces, in the order they run:
| Piece | Runs | Responsibility |
|---|---|---|
TenantResolver | per request — authoritative ones (subdomain, domain, route) first, then fallbacks (header), each in list order | Maps the request to a TenantRef — { id } or { domain } |
TenantSource | once a resolver produced a ref | Loads the tenant record (find / findByDomain). An unknown ref from an authoritative resolver ends resolution with no tenant; from a fallback it moves on to the next fallback |
ctx().tenant | for the rest of the request | The resolved open record — undefined when nothing matched |
tenancy:switched | on every entry into a tenant | Lets cache, storage and the db client re-attach their per-tenant instance |
tenancy:exited | when a tenancy.run() callback settles | Releases what a tenancy:switched listener took (the leased database client) |
tenancy:created | once, after a new tenant is created and provisioned | Welcome email, audit entry, notifying a panel — a listener may assume the tenant's storage exists |
Outside a request there is no resolver, so you enter a tenant explicitly with tenancy.run(id, fn) — jobs, CLI commands and maintenance scripts all go through it, and the same hook fires.
Resolution is identification, never authorization
A resolved tenant only says which tenant the request claims to be about. It does not check that the caller belongs to it — with headerResolver a logged-in user of tenant A can simply send x-tenant-id: b. Enforce membership separately with tenantMembershipPlugin from Teams, which rejects non-members app-wide with 403 TEAM_NOT_A_MEMBER.
Quickstart
A complete app that boots and serves one tenant-aware route:
import { createApp, ctx } from '@basaltkit/core'
import { fastifyPlugin, route, FASTIFY } from '@basaltkit/fastify'
import { tenancyPlugin, MemoryTenantSource, headerResolver } from '@basaltkit/tenancy'
const app = await createApp({
plugins: [
tenancyPlugin({
source: new MemoryTenantSource().add({ id: 'acme', name: 'Acme Inc', plan: 'pro' }),
resolvers: [headerResolver()], // x-tenant-id: acme
}),
fastifyPlugin({
routes: [
route({
method: 'GET',
url: '/whoami',
async handler() {
const tenant = ctx().tenant
return { tenant: tenant?.id ?? null, plan: tenant?.plan ?? 'free' }
},
}),
],
}),
],
}).boot()
await app.container.get(FASTIFY).listen({ port: 3000 })curl http://localhost:3000/whoami -H 'x-tenant-id: acme'
# → {"tenant":"acme","plan":"pro"}
curl http://localhost:3000/whoami
# → {"tenant":null,"plan":"free"} (no tenant resolved — see `required` below)Resolvers
A resolver maps an incoming request to a tenant reference. You pass a list, and resolvers come in two kinds:
- Authoritative —
subdomainResolver,domainResolver,routeResolver, and any custom resolver wrapped inauthoritative(fn). They read something the platform controls, so they always run first, whatever the list order; the first reference that loads an existing tenant wins. If an authoritative resolver names a tenant that does not exist, the request resolves to no tenant — it never falls through to a client-controlled resolver. - Fallback —
headerResolverand unmarked custom resolvers. They run, in list order, only when no authoritative resolver named anything (the bare apex,www,localhost).
So nosuch.basalt.app with x-tenant-id: globex is not globex, and a header can never override acme.basalt.app. A reference whose id fails the tenant-id grammar (see below), or whose domain is not a valid hostname, counts as not found and never reaches the source.
import {
tenancyPlugin,
MemoryTenantSource,
headerResolver,
subdomainResolver,
} from '@basaltkit/tenancy'
tenancyPlugin({
source: new MemoryTenantSource()
.add({ id: 'acme', name: 'Acme Inc' })
.add({ id: 'globex', name: 'Globex' }),
resolvers: [
subdomainResolver({ base: 'basalt.app' }), // acme.basalt.app — authoritative
headerResolver(), // x-tenant-id: acme — only on the bare apex
],
})Prefer an error to a precedence rule when resolvers disagree? Pass onConflict: 'error': every resolver runs, and two that load different tenants answer 400 TENANCY_CONFLICT (at the cost of one lookup per resolver).
The four built-in resolvers
import {
subdomainResolver,
domainResolver,
headerResolver,
routeResolver,
} from '@basaltkit/tenancy'
// acme.basalt.app → { id: 'acme' }. Ignores 'www', the bare base domain,
// nested subdomains (a.b.basalt.app), and the port.
subdomainResolver({ base: 'basalt.app' })
// app.acme.com → { domain: 'app.acme.com' }, looked up via source.findByDomain.
// Requires the source to implement findByDomain (see below).
domainResolver()
// Reads an HTTP header (default 'x-tenant-id') → { id: <value> }.
headerResolver() // x-tenant-id: acme
headerResolver({ header: 'x-org' })
// Reads a route param (default 'tenant') → { id: params.tenant }.
// Matches routes like /t/:tenant/...
routeResolver() // /t/acme/...
routeResolver({ param: 'org' }) // /o/:org/...Don't trust a browser-supplied header in production
headerResolver is ideal for development and internal traffic, but a user can send x-tenant-id: another-customer by hand. In production prefer subdomainResolver / domainResolver (DNS is under your control), and verify the authenticated user belongs to the resolved tenant.
Custom resolvers
A resolver is just a function (request) => TenantRef | null (async allowed), where request is the neutral { headers?, params?, url? } shape and a TenantRef is { id } or { domain }. Write your own when the built-ins don't fit — e.g. deriving the tenant from a claim your gateway signed and put on the request. An unmarked resolver is a fallback; wrap it in authoritative() only when clients cannot forge its input:
import { authoritative } from '@basaltkit/tenancy'
const claimResolver = authoritative((request) => {
const org = request.headers?.['x-org-claim'] // set by the gateway, stripped from client requests
return typeof org === 'string' ? { id: org } : null
})
tenancyPlugin({ source, resolvers: [claimResolver, subdomainResolver({ base: 'basalt.app' })] })MemoryTenantSource is for development and tests. In production use a durable TenantSource (below) — or implement the contract over your own database.
The TenantSource contract
A tenant is an open record — { id, ...anything } — so you can attach any per-tenant fields (name, plan, domains, settings…) and they round-trip unchanged. A TenantSource is where those records live; the full interface is small:
import type { TenantSource } from '@basaltkit/tenancy'
const source: TenantSource = {
async find(id) { /* SELECT … WHERE id = ? */ return null }, // required
async findByDomain(domain) { return null }, // optional — needed by domainResolver()
async list() { return [] }, // optional — needed by tenancy.forEach()
}You rarely write this by hand — use MemoryTenantSource in dev, or a durable source in production (both shown below). Only implement the interface yourself when tenants already live in a table you own.
Custom domains (verified)
domainResolver() maps app.acme.com → { domain }, then findByDomain loads the tenant. But you must not let a tenant claim a domain they don't own. CustomDomains manages that: register a domain (unverified), prove ownership with a DNS TXT record, and only verified domains resolve.
import { CustomDomains, findByVerifiedDomain } from '@basaltkit/tenancy'
const domains = new CustomDomains({ store }) // store defaults to in-memory
// 1. Tenant adds their domain → you show them the DNS record to publish
const { dns } = await domains.add('acme', 'app.acme.com')
// dns → { type: 'TXT', host: '_basalt-verify.app.acme.com', value: 'basalt-domain-verify=…' }
// 2. Once they've added it, verify — a real DNS lookup confirms the token.
// verify/instructions/remove are scoped to the owning tenant.
if (await domains.verify('acme', 'app.acme.com')) { /* live */ }
// 3. Wire verified domains into your source with the built-in helper — a forged
// or unverified Host header can never resolve to a tenant.
const source: TenantSource = {
async find(id) { /* … */ },
findByDomain: findByVerifiedDomain(domains, (id) => /* load tenant */ this.find(id)),
}An unverified claim does not block the real owner forever. After claimTtlMs (72 h by default) another tenant's add() takes the domain over; with challengeSecret set the owner need not wait — it publishes the record returned by domains.challenge(tenantId, domain) and its add() wins immediately, already verified. Set reservedDomains to your platform apex so nobody can claim it or any subdomain of it:
const domains = new CustomDomains({
store,
reservedDomains: ['basalt.app'], // DOMAIN_RESERVED for basalt.app and *.basalt.app
challengeSecret: env.DOMAIN_CHALLENGE_SECRET, // same value on every instance
})Domains are held to the RFC 1123 hostname grammar: normalizeDomain() rejects userinfo (acme.basalt.app@evil.com), paths, %-escapes, non-ASCII and IP literals with 400 DOMAIN_INVALID instead of rewriting them. Register an internationalized domain in its xn-- form (domainToASCII() from node:url).
verify() does a live TXT lookup via node:dns (injectable for tests). TLS certificate provisioning is infrastructure — issue the cert with your platform (Cloudflare, Caddy, ACME) once verify() returns true.
A durable domain store
MemoryDomainStore forgets every claim and proof on restart. The two durable tenant sources each ship a matching store on the same tenant_domains table:
import { prismaDomainStore, prismaTenantSource } from '@basaltkit/tenancy-prisma'
// or: import { sqliteDomainStore, sqliteTenantSource } from '@basaltkit/tenancy-sqlite'
const tenants = prismaTenantSource(prisma)
const domains = new CustomDomains({
store: prismaDomainStore(prisma), // sqliteDomainStore(tenants.db) for SQLite
reservedDomains: ['basalt.app'],
})
tenancyPlugin({ source: tenants, resolvers: [subdomainResolver({ base: 'basalt.app' }), domainResolver()] })No findByVerifiedDomain is needed with these: the source's own findByDomain is fail-closed, so a claim resolves only once verified and a domain another tenant merely claimed (victim.com) never routes a request. The table holds two kinds of row, told apart by verificationToken:
| Row | Written by | save() / provision() | Resolves |
|---|---|---|---|
mirror (verificationToken NULL) | the source, from tenant.domains | kept in line with tenant.domains | always |
claim (verificationToken set) | the domain store | never deleted | once verified |
So re-provisioning a tenant or changing its status never erases a verified custom domain or its proof. A domain is one row whichever kind it is: claiming a domain already on some tenant.domains throws DOMAIN_TAKEN (409), translated from the driver's unique violation inside the store.
The Prisma store needs the verification columns of the bundled TenantDomain model (verificationToken, verified, createdAt, verifiedAt) — an additive migration: re-run basalt prisma:sync, then prisma migrate dev. The SQLite source adds them on open.
Writing a store of your own? Run the shared contract against it — it lives on a test-only subpath and works with any runner:
import { domainStoreContract } from '@basaltkit/tenancy/testing'
describe('MyDomainStore', () => {
for (const c of domainStoreContract(() => new MyDomainStore(db))) it(c.name, c.run)
})Creating tenants
How you create a tenant depends on the backend.
Tenant ids follow one grammar
A tenant id is not an opaque label: it becomes a namespace segment in the cache (tenant:<id>:), in storage (tenants/<id>/), in realtime channels and in schema names. tenancy.create() and MemoryTenantSource.create()/save() therefore refuse, with InvalidTenantIdError (400 TENANT_ID_INVALID), any id outside /^[a-z0-9][a-z0-9_-]{0,62}$/ or equal to the reserved global — so a self-serve signup cannot pick globex:user, globex/files or .. to alias another tenant's keys or files. Slugs, UUIDs and cuids fit. isValidTenantId(id) is exported for your own signup form; pass validateTenantId to tenancyPlugin (and the same function to new MemoryTenantSource({ validateTenantId })) to narrow or widen it — keep :, /, \, ., whitespace and control characters out of any replacement.
In dev — MemoryTenantSource
Seed them inline; the add() calls chain. Lost on restart, so dev/tests only:
const tenants = new MemoryTenantSource()
.add({ id: 'acme', name: 'Acme Inc' })
.add({ id: 'globex', name: 'Globex', domains: ['app.globex.com'] })
tenancyPlugin({ source: tenants, resolvers: [subdomainResolver({ base: 'basalt.app' })] })Durably — @basaltkit/tenancy-sqlite / -prisma
For production, don't hand-roll the contract — a durable TenantSource persists tenants across a restart. Both ship create/save/find/findByDomain/list/remove:
import { sqliteTenantSource } from '@basaltkit/tenancy-sqlite' // single node, zero-dep
// import { prismaTenantSource } from '@basaltkit/tenancy-prisma' // Postgres/MySQL
const tenants = sqliteTenantSource('./data/tenants.db')
// save() is an upsert — create or update a tenant. Any extra field round-trips.
await tenants.save({ id: 'acme', name: 'Acme Inc', plan: 'pro', domains: ['app.acme.com'] })
// create() only inserts — an id that already exists throws TenantAlreadyExistsError.
await tenants.create({ id: 'globex', name: 'Globex' })
tenancyPlugin({
source: tenants,
resolvers: [subdomainResolver({ base: 'basalt.app' }), domainResolver()],
})save and create bring the tenant's domain rows in line with tenant.domains (domains claimed through CustomDomains are left alone — see a durable domain store); a domain already owned by another tenant is rejected (routing must be unambiguous). See Persistence.
Prisma-backed registry
prismaTenantSource(prisma) stores the registry in the Postgres/MySQL database you already run — ideal for multiple instances sharing one tenant list. Add its two models with basalt prisma:sync --push, then pass your generated PrismaClient. Same create/save/find/findByDomain/list/remove surface.
At sign-up — provision a tenant on demand
A real SaaS creates tenants when a customer signs up, and the person clicking Create in a panel usually has neither the knowledge nor the access to run a migration afterwards. Declare onProvision once, and every creation path — an admin route, basalt tenant:create, a seed script — brings the tenant's storage into existence before anything can route a request to it.
// src/app.ts
import { provisionTenantSchema, tenantSchema, migrateTenants } from '@basaltkit/prisma'
import { PrismaPg } from '@prisma/adapter-pg'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })
tenancyPlugin({
source,
resolvers: [subdomainResolver({ base: 'example.com' })],
async onProvision(tenant) {
const admin = new PrismaClient({ adapter })
await provisionTenantSchema(admin, tenantSchema(tenant.id)) // CREATE SCHEMA IF NOT EXISTS
await migrateTenants({
tenants: [tenant.id],
target: { mode: 'schema', url: process.env.DATABASE_URL!, provision: admin },
})
},
})Then create through the service, never through the source:
// src/modules/tenants/tenants.routes.ts
route({
method: 'POST',
url: '/tenants',
meta: { auth: true }, // admin-guarded
body: z.object({ id: z.string().min(1), name: z.string() }),
async handler({ body }) {
// persists → provisions → emits tenancy:created, in that order
return ctx().container.get(TENANCY).create(body)
},
})basalt tenant:create acme --name=Acme
# → Created and provisioned tenant "acme".source.create() skips all of this
The source only writes the row. A tenant whose record exists but whose schema does not is routable immediately — subdomainResolver will send it traffic the moment it is saved — and its first request dies on a raw database error. Going through tenancy.create() is what closes that window.
create() never overwrites an existing tenant
An id that already exists — whatever its status — is refused with TenantAlreadyExistsError (409 TENANT_ALREADY_EXISTS) before anything is written: no hook fires and onProvision does not run, so a double-submitted signup cannot replace a tenant's owner or re-provision live storage. A tenant left failed (or still provisioning) is finished with tenancy.provision(id), not by creating it again; an intentional update of the record is source.save(). The durable sources refuse the duplicate in the insert itself, so of two concurrent creates of the same id exactly one wins.
onProvision runs inside the new tenant's context, so ctx().tenant and any tenant-scoped client resolve correctly — the same contract as onMigrate and onSeed. Seeding starter data belongs here too:
async onProvision(tenant) {
await provisionTenantSchema(admin, tenantSchema(tenant.id))
await migrateTenants({ tenants: [tenant.id], target })
await db<PrismaClient>().setting.create({ data: { key: 'onboarded', value: 'true' } })
}React to the finished tenant with the hook — it fires only after provisioning succeeded, so you can safely touch the new tenant's data:
app.hooks.on('tenancy:created', async ({ tenant }) => {
await mailer.send({ to: owner(tenant), subject: `${tenant.name} is ready` })
})Make onProvision idempotent
If it throws, the error reaches your caller and tenancy:created does not fire — but the tenant record was already written, because the source persists first. That half-state is deliberately not rolled back: not every TenantSource can delete, and a failed delete on top of a failed provision destroys the evidence. Write it so a retry — tenancy.provision(id) — can finish the job: CREATE SCHEMA IF NOT EXISTS, migrate deploy.
It also runs inline: an HTTP handler calling create() waits for the whole migration. That is fine for a schema and a handful of migrations, and wrong for anything slow — hand the slow part to a queued job and let the route return.
The address a tenant is created with
Every durable TenantSource reads a tenant's addresses from one key — tenant.domains — and an application that never passes it creates tenants with none. Silently, too: subdomainResolver slices the suffix off the Host and answers without ever consulting the table, so the tenant serves traffic and what is missing is only the record that the address belongs to it.
Nothing breaks until something needs that record. domainResolver() cannot find the tenant, a custom domain cannot be attached to it, and nothing stops a second tenant claiming the same address — the uniqueness lives in the table that stayed empty. It is the worst kind of gap: it does not fail, it omits. An installation can run for a year with an empty domain set and discover it when the first customer asks for their own domain, with every historical row to backfill.
Declare it once, on the plugin:
tenancyPlugin({
source,
resolvers: [subdomainResolver({ base: 'example.com' })],
canonicalDomain: (tenant) => `${tenant.id}.${process.env.APP_DOMAIN}`,
})tenancy.create() applies it before the record is persisted, so every creation path gets it — public signup, an admin route, basalt tenant:create, a seed script — instead of each one remembering. Return undefined to decline, for a tenant that should have no address of its own.
It is added, never substituted
The canonical domain joins whatever the tenant already declares. Sources replace the whole domain set on save, so substituting would erase a customer's own app.acme.com the next time anything called create().
When provisioning outlives the request
onProvision runs inline by default: create() waits for it, and the caller knows the tenant is usable when it returns. That is right for a schema and a handful of migrations, and wrong once the work is slow enough to outlive an HTTP request.
Switch to provision: 'deferred' and create() returns as soon as the record is written, marked provisioning:
tenancyPlugin({ source, resolvers, onProvision, provision: 'deferred' })const tenant = await tenancy.create({ id: 'acme' })
tenant.status // 'provisioning'
// …and requests routed to it get 503 until it is finishedNothing is scheduled for you, and that is deliberate. Background work runs in another process, where a closure from this one cannot reach — so the worker re-enters with the id:
// jobs/provision-tenant.ts
export const ProvisionTenant = defineJob({
name: 'tenant.provision',
handle: ({ id }: { id: string }) => ctx().container.get(TENANCY).provision(id),
})
// wherever you create the tenant
await tenancy.create({ id }) // returns immediately, 'provisioning'
await ctx().container.get(QUEUE).dispatch(ProvisionTenant, { id })provision(id) runs onProvision, flips the status to ready and emits tenancy:created — the same finish line the inline path crosses. Keep it idempotent: after a failure the status is failed, and a retry has to be able to complete the job. It refuses a suspended or deleting tenant (TenantNotProvisionableError): writing ready there would lift a suspension or revive a tenant halfway through destroy().
That design keeps @basaltkit/queue out of @basaltkit/tenancy entirely. The app owns the dispatch, so any scheduler works — a queue, a cron, or by hand, basalt tenant:provision <id>.
The status, and why 503
| Status | Serves requests | How it gets there |
|---|---|---|
(none, or null) | ✅ | Every tenant created before provisioning existed. Treated as ready — anything else would take a production estate offline on upgrade |
ready | ✅ | onProvision succeeded |
provisioning | ❌ 503 | create() wrote the record; the work has not finished |
failed | ❌ 503 | onProvision threw. The record is kept, not deleted — it is the evidence the tenant was attempted |
deleting | ❌ 503 | destroy() has started. Marked before the storage is touched, so no request reaches a schema being dropped underneath it |
suspended | ❌ 403 TENANT_SUSPENDED | Your app wrote it — billing lapsed, abuse. Tenancy never sets it |
anything else (active, disabled, …) | ❌ 500 TENANT_STATUS_UNKNOWN | A value tenancy does not recognise. Refused rather than guessed at |
503, not 404. The tenant exists; it is simply not serving yet, and 503 is the status a client may retry. A 404 would say the opposite.
A suspension is 403, not 503. The storage is fine and retrying will not help — the account is locked out until the app lifts the suspension. Lock a tenant out with source.save({ ...tenant, status: 'suspended' }); put it back with 'ready'.
An unknown status fails closed. If your records say active for a serving tenant, tenancy cannot know that means "the storage is usable", so the request is refused with a message naming the value it saw. Store ready (or no status) instead. assertTenantServing(tenant) runs the same check outside HTTP; isTenantReady(tenant) is its boolean form.
Reading the tenant
The resolved tenant lives in the request context — no argument passing. It's the open record you stored, so any custom field is right there:
import { ctx } from '@basaltkit/core'
export async function currentTenant() {
const tenant = ctx().tenant // undefined outside a tenant context
return {
id: tenant?.id ?? null,
name: tenant?.name ?? null, // any field you saved round-trips
plan: tenant?.plan ?? 'free',
}
}Set required: true on the plugin to reject unresolved requests up front with a 404 TENANCY_NOT_RESOLVED — misrouted requests fail loudly instead of running against global data.
true applies to every route, which most apps cannot live with: a health check has no tenant to send, and neither does a landing page or a public pricing endpoint. Exempt them by path instead of giving up the guard everywhere:
tenancyPlugin({
source: tenants,
resolvers: [headerResolver()],
required: { except: ['/', '/health', '/openapi.json', /^\/public\//] },
})Entries are exact strings or regular expressions, matched against the path without its query string — so /health still covers /health?probe=1. A URL that cannot be matched at all is treated as required, so the guard fails closed.
Separating central routes from tenant routes
A path list works, but it puts the decision in a different file from the route it describes: rename the URL and the exemption silently stops matching. Declare it on the route instead, with meta.tenant:
// A central route: no tenant, ever.
route({ method: 'GET', url: '/pricing', meta: { tenant: false }, handler })
// A tenant route: refuse the request if none resolved.
route({ method: 'GET', url: '/invoices', meta: { tenant: true }, handler })meta.tenant overrides the app-wide required in both directions, so the combination most apps want is deny by default, opt out per route:
tenancyPlugin({ source: tenants, resolvers: [headerResolver()], required: true })Every route now needs a tenant, and the handful of central ones — health check, landing page, sign-up, tenant creation — say so next to their handler, where a reviewer sees it. required: { except } remains available and still works; use it for paths you do not own, such as routes mounted by another package.
A route that declares meta: { tenant: false } still resolves a tenant when one is present, so ctx().tenant is populated on acme.example.com/pricing. Only the requirement is lifted.
Central-only routes: tenant: 'never'
Some routes must not run inside a tenant at all — the SaaS owner's console: plans, tenant approval, operator roles. tenant: false is not enough there: on acme.example.com/platform/plans the tenant still resolves, the request runs against Acme's storage, and a tenant owner holding '*' satisfies can: 'platform:…'. Declare those routes 'never':
route({
method: 'GET',
url: '/platform/plans',
meta: { tenant: 'never', auth: true, can: 'platform:plans.read' },
handler,
})When a tenant resolves on such a route, the request is answered with the body an unmatched route gets — 404 { error: { code: 'NOT_FOUND', message: 'Route not found.' } } (CentralOnlyRouteError) — before any guard runs, so a 401 or 403 never reveals that the route exists. The tenant is not attached to the context and tenancy:switched is not emitted. On the apex, where no tenant resolves, the route runs normally. The behaviour is the same on Fastify, Express and Hono.
List tenancyPlugin before the auth plugins
The check runs in the tenancy enricher, and enrichers run in plugin order. The authPlugin and apiKeysPlugin enrichers can refuse a request themselves (a 401 for an invalid or expired bearer, a 400 for two disagreeing API keys); if they come first, that answer reaches the caller instead of the 404 and tells it the route exists. Put tenancyPlugin ahead of them in plugins: [...].
meta.tenant | No tenant resolved | A tenant resolved |
|---|---|---|
| (absent) | app-wide required decides | runs in the tenant |
true | 404 TENANCY_NOT_RESOLVED | runs in the tenant |
false | runs without a tenant | runs in the tenant |
'never' | runs without a tenant | 404 NOT_FOUND, handler not run |
Any other value ('none', 'optional', 'false', 0, null) refuses the boot with HTTP_INVALID_ROUTE_META, naming every offending route, on every adapter: a typo for 'never' would otherwise fall back to the app-wide default and serve the route on tenant hosts. (@basaltkit/tenancy 3.2 only warned and fell back.) basalt ai doctor warns about routes that pair tenant: false with a platform: permission.
mcpPlugin runs the same check over the routes it exposes as MCP tools. A route that skips it — a custom driver calling runRoute() without assertRouteMetaValid() — fails closed on each request: isTenantRequired() and the tenancy enricher throw InvalidTenantMetaError (TENANCY_INVALID_ROUTE_META, 500) before resolving any tenant, instead of falling back to required. The driver must pass the app's enrichers (http:enrichers) to runRoute(), as every adapter does; passing them without a container is refused too (HTTP_ENRICHERS_UNRUNNABLE, @basaltkit/http 3.0), so the enricher can no longer be skipped in silence.
Exempting a path only lifts the tenant requirement. Auth, subscription checks and every other guard still run.
Keeping required: false is still valid when central routes outnumber tenant ones, but then every handler is responsible for the absent tenant itself.
You can also read the tenant through the TENANCY facade — handy in services that don't otherwise touch ctx():
import { TENANCY } from '@basaltkit/tenancy'
const tenancy = app.container.get(TENANCY)
tenancy.current() // Tenant | undefined — the active context's tenant
await tenancy.find('acme') // Tenant | null — look one up by id, ignoring contextAutomatic isolation
You don't isolate anything by hand. The same code behaves per tenant:
await cache.put('config', value) // key prefixed with tenant:<id>
await storage.disk('uploads').put(path, f) // stored under tenants/<id>/
await SendEmail.dispatch({ userId }) // tenant restored in the worker
logger.info('done') // log carries tenantIdFail-closed scoping — the tenantScoped() family
Database rows are the one place isolation is YOUR job: a repository that forgets the tenantId filter returns every tenant's rows — and with Prisma, where: { tenantId: ctx().tenant?.id } silently drops the filter when the tenant is undefined, turning a bug into a cross-tenant data leak that returns 200 OK. The three helpers exported from @basaltkit/tenancy never do that: when there is nothing to scope to they throw rather than return undefined.
| Helper | Signature | Returns | Throws when |
|---|---|---|---|
requireTenant() | () => Tenant | The whole tenant record of the active context | No tenant in context |
requireTenantId(fallback?) | (fallback?: string) => string | The context tenant's id; else fallback | No context tenant and no fallback |
tenantScoped(where?) | <W>(where?: W) => W & { tenantId: string } | Your where clause with the context tenant's tenantId merged in last | No tenant in context — a tenantId in where is never used as a fallback |
All three throw TenantRequiredError (400 TENANT_REQUIRED).
import { requireTenant, requireTenantId, tenantScoped, TenantRequiredError } from '@basaltkit/tenancy'
// A query that can never run unscoped:
const rows = await db.project.findMany({ where: tenantScoped({ archived: false }) })
// → { archived: false, tenantId: 'acme' }
// The whole record, when you need more than the id:
const plan = requireTenant().plan
// System code (a job, a CLI command) may pin one tenant deliberately:
const tenantId = requireTenantId(job.tenantId)Three guarantees are worth stating exactly, because they are what makes the family safe to use on input-derived data:
- The context tenant always wins.
tenantScoped()spreadstenantIdlast, so atenantIdsmuggled intowhereby client input cannot widen or switch the scope:tenantScoped({ tenantId: 'globex' })inside Acme's context still yields{ tenantId: 'acme' }. tenantScoped()takes the tenant from the context only. AtenantIdinsidewhereis never a fallback:whereis routinely built from client input, and with no tenant resolved (requireddefaults tofalse) that would let a request pick any tenant by omitting its tenant header. SotenantScoped({ tenantId: 'globex' })with no context tenant throws.- An explicit id is honoured only by
requireTenantId(fallback), and only when there is no context tenant. That is the system-code path — a queue worker orbasaltcommand pinning one tenant (or wrap the work intenancy.run(id, …)). Inside a request it can never override the resolved tenant. - With neither, it throws. The value is always a real tenant id, never a filter that silently disappears. That is the whole point: a
400beats a cross-tenant read.
The same shape elsewhere
@basaltkit/activity exposes the same idea as a query option: new Activity({ tenantScoped: 'required' }) makes its trail queries throw instead of silently returning every tenant's rows. Several packages ship their own fail-closed variant of the check — SEARCH_TENANT_REQUIRED, FILE_TENANT_REQUIRED, COMMENT_TENANT_REQUIRED, AUDIT_TENANT_REQUIRED — all with the same meaning: pass a tenantId or run inside a tenant context.
These checks are conditional on tenancy being registered. tenancyPlugin sets a tenancy:active marker in the container metadata, and every generic package reads it to decide whether to fail closed: with tenancy on, SEARCH_TENANT_REQUIRED / FILE_TENANT_REQUIRED / COMMENT_TENANT_REQUIRED / AUDIT_TENANT_REQUIRED / MissingCacheScopeError all apply; with tenancy off, there is no tenant dimension and the same calls simply work unscoped. That is the beyond-SaaS rule — a generic package never requires tenancy. @basaltkit/cache was the first to use the marker, flipping its onMissingScope default from 'global' to 'error' in multi-tenant apps; see Caching.
Running code in a tenant
Outside a request — in a job, a script, or maintenance — there's no resolver, so you enter a tenant explicitly. run() sets ctx().tenant, emits tenancy:switched (which re-attaches the tenant's cache, storage, db client…), and restores the surrounding context afterwards:
import { TENANCY } from '@basaltkit/tenancy'
import { db } from '@basaltkit/prisma'
const tenancy = app.container.get(TENANCY)
// Pass an id (loaded from the source; throws TenantNotFoundError if unknown)
// or a Tenant object you already have.
const total = await tenancy.run('acme', async () => {
return db<PrismaClient>().invoice.count() // scoped to Acme
})
// Bulk maintenance: visits every tenant, each in its own context, with bounded
// concurrency (default 5). Requires source.list().
await tenancy.forEach(async (tenant) => {
await tenancy.run(tenant, async () => {
// …per-tenant work, fully isolated…
})
}, { concurrency: 5 })Enter only a serving tenant
Only the HTTP enricher checks a tenant's status. run() enters whatever it is given — a provisioning, suspended or deleting tenant included — because provisioning and maintenance must be able to. Code that acts for a tenant outside a request (a refresh by cookie, a job, a command, a webhook retry) asks for the check:
await tenancy.run(job.tenantId, () => sendInvoices(), { serving: true }){ serving: true } runs assertTenantServing before the context is entered and before any hook fires, with the enricher's errors: TenantNotReadyError (503) for provisioning / failed / deleting, TenantSuspendedError (403) for suspended, TenantStatusUnknownError (500) for a status tenancy does not know. Given an id, the status is the one just loaded from the source; given a Tenant object, its own status is checked — pass the id when the object may be stale.
The rule: outside a request, enter a tenant only if it is serving — unless the work is the lifecycle (provisioning, onDeprovision, a migration).
Make it the default
A flag at every call site protects only the calls that remember it. Turn the check on once, at the composition root, and every run() gets it:
tenancyPlugin({ source, resolvers, servingByDefault: true })Now tenancy.run(id, fn) refuses a tenant that is not serving, and so does the 'tenancy:run' signal that queue workers and webhook deliveries use. Code that must enter such a tenant says so with { serving: false }. The framework's own lifecycle paths already do: provision(), destroy(), forEach() and the tenant:migrate, tenant:seed and tenant:run commands enter every tenant whatever its status. Your own lifecycle code (a migration loop, a restore) passes { serving: false } too. forEach() hands you suspended tenants as well, so check tenant.status inside it when the work is for the tenant.
servingByDefault is false in 4.x, so turning it on is your call. It becomes the default in the next major of @basaltkit/tenancy, when { serving: false } is the only way into a tenant that is not serving.
React to context switches anywhere with the hook:
app.hooks.on('tenancy:switched', ({ tenant }) => {
logger.info(`working for tenant ${tenant.id}`)
})A package that must enter a tenant from background code, without depending on @basaltkit/tenancy, reads the same function from the 'tenancy:run' metadata signal (type TenantRunner): same id check, same TenantNotFoundError, same tenancy:switched/tenancy:exited pair, and the status check only under servingByDefault. It runs from the caller's context, so enter from runWithContext({}, ...) when nothing ambient may leak in. @basaltkit/webhooks uses it for the endpoint lookup of off-request dispatches — see Webhooks → Schema-per-tenant.
CLI commands
tenancyPlugin registers six commands into the CLI bucket, so they show up as soon as @basaltkit/cli is present — no extra wiring:
| Command | Needs | What it does |
|---|---|---|
basalt tenant:list | source.list() | Tabulates every tenant (scalar fields only) |
basalt tenant:create <id> [--name=… --anyField=…] | source.create() or save() | Persists a new tenant; every flag becomes a field. An existing id is refused (exit code 1). With provision: 'deferred' it says the tenant is still provisioning |
basalt tenant:provision <id> | onProvision | Finishes or retries a provisioning/failed tenant (tenancy.provision(id)): runs the hook, writes ready and emits tenancy:created. Exit code 1 when the hook throws (the tenant stays failed); refuses a suspended or deleting tenant |
basalt tenant:destroy <id> [--force] [--yes] | source.delete() | Marks the tenant deleting, runs onDeprovision in its context, then removes the record. Asks first; --yes skips the question, --force removes the record even if teardown failed |
basalt tenant:migrate [--tenant=<id>] | onMigrate | Runs your per-tenant migration hook inside each tenant's context |
basalt tenant:seed [--tenant=<id>] | onSeed | Runs your per-tenant seed hook inside each tenant's context |
basalt tenant:run <id> <command> [args…] | — | Runs any other registered command inside one tenant's context |
onMigrate / onSeed are where the DB-specific work goes — the framework only iterates tenants and enters each context:
tenancyPlugin({
source: tenants,
resolvers: [subdomainResolver({ base: 'basalt.app' })],
onMigrate: async (tenant) => { await migrateSchemaFor(tenant.id) },
onSeed: async (tenant) => { await db<PrismaClient>().plan.create({ data: { name: 'free' } }) },
})A missing hook is reported (No migrate hook configured. …) with exit code 1 rather than silently doing nothing; a TenantSource that doesn't implement list() / create() is reported the same way.
Isolation modes
@basaltkit/prisma implements three isolation strategies. Your query code stays db<PrismaClient>().user.findMany() in all three — the mode is prismaPlugin configuration, not a rewrite. Pick one:
| Mode | How | Isolation | When |
|---|---|---|---|
| Shared database | one client, tenancyExtension() adds a tenantId filter | logical | most apps; cheapest to run |
| Schema per tenant | one database, one PostgreSQL schema per tenant | strong | isolation without N databases |
| Database per tenant | a separate database (+ client) per tenant | strongest | compliance, per-tenant backups |
Shared database (default) — one client with a tenantId column on each model. The extension forces the current tenant's filter onto every read and update, stamps it onto every create (nested creates included), narrows nested connect/update/delete to the tenant, refuses to move a row to another tenant, and refuses raw or unknown operations inside a tenant context — code can't forget or override it:
import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'
import { prismaPlugin, tenancyExtension } from '@basaltkit/prisma'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })
const db = new PrismaClient({ adapter }).$extends(
tenancyExtension({
tenantField: 'tenantId', // column name (default 'tenantId')
// onMissingTenant defaults to 'error': no tenant in context → throws
// PRISMA_TENANT_MISSING instead of running across every tenant.
}),
)
prismaPlugin({ client: db })
// Deliberate cross-tenant reads (back-office, jobs) get their OWN client —
// never put 'bypass' on the app's main client.
export const adminDb = new PrismaClient({ adapter }).$extends(
tenancyExtension({ onMissingTenant: 'bypass' }),
)The extension works on query arguments, so it can't tell which scalar columns are foreign keys (data: { projectId } is not checked). Use composite foreign keys (tenantId, id) and RLS as the database-level guarantee. tenancyExtension({ rls: true }) sets the tenant for Postgres RLS on every operation — see the RLS part of the Security guide.
Schema per tenant — one database, one PostgreSQL schema per tenant. Each tenant gets a client whose connection URL carries ?schema=tenant_<id>, so Prisma sets the search_path at connect time (reliable, unlike per-request search_path switching on a shared pool). Clients are held in a bounded pool (only idle clients are evicted; see the per-tenant client pool):
import { PrismaClient } from '@prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'
import { prismaPlugin, provisionTenantSchema, tenantSchema, pgSchemaClient } from '@basaltkit/prisma'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })
prismaPlugin({
schemaPerTenant: {
url: env.DATABASE_URL,
// pgSchemaClient sets the tenant's schema on the connection (search_path):
// a Prisma 7 driver adapter ignores the URL's ?schema= on its own.
createClient: pgSchemaClient(({ connectionString, schema }) =>
new PrismaClient({ adapter: new PrismaPg({ connectionString }, { schema }) })),
prefix: 'tenant_', // schema = tenant_<id> (default)
},
destroy: (client) => client.$disconnect(), // close a client evicted from the pool
max: 25, // most-recently-used clients kept open (default 10)
})
// Provision a new tenant's schema (an admin connection with $executeRawUnsafe):
const admin = new PrismaClient({ adapter })
await provisionTenantSchema(admin, tenantSchema('acme')) // CREATE SCHEMA IF NOT EXISTS "tenant_acme"Prisma 7: wrap the factory in pgSchemaClient
A Prisma 7 driver adapter ignores ?schema=, so a createClient that only forwards the URL puts every tenant in public. pgSchemaClient hands the factory the tenant's schema, for the adapter's schema option (Prisma's model queries use it), and a connection whose search_path is that schema (raw SQL resolves against it). It fails closed: a URL without a schema throws instead of connecting to public.
Prisma 8 is different. Its queries name the schema in the SQL itself ("public"."Project"), so the search_path does not choose it, and its client has no schema option. pgSchemaClient does not carry schema-per-tenant over to Prisma 8. Basalt tests the Prisma 8 release candidate in apps/prisma8-integration and will ship a supported path when Prisma 8 is stable.
tenantSchema() is injective: canonical ids (acme, acme_co) are used as-is, and any other id (ACME, acme-co, UUIDs) gets a __<hash> suffix (tenant_acme_co__<16 hex>), so a new tenant can never land in an existing tenant's schema. Evicted pool clients are closed with $disconnect() by default, and concurrent first requests for a tenant share one client.
Database per tenant — a separate database (and client) per tenant, via the same LRU pool. Give it a factory keyed by tenant id:
import { PrismaPg } from '@prisma/adapter-pg'
prismaPlugin({
forTenant: (id) => new PrismaClient({ adapter: new PrismaPg({ connectionString: urlFor(id) }) }),
destroy: (client) => client.$disconnect(),
max: 20,
})In every mode the plugin attaches the right client to the context on each HTTP request and inside tenancy.run() — you read it with db<PrismaClient>(), which throws DB_UNAVAILABLE outside a tenant context. See Database-per-tenant for the full pooled recipe.
Migrations per tenant
Schema- and database-per-tenant need migrations run for each tenant. migrateTenants orchestrates it — bounded concurrency, provisioning the schema first (schema mode), and a per-tenant report where one failure never aborts the rest. Wire it as a basalt tenant:migrate command:
import { tenantMigrateCommand, provisionTenantSchema } from '@basaltkit/prisma'
import { commandsPlugin } from '@basaltkit/cli'
commandsPlugin([
tenantMigrateCommand({
tenants: () => tenants.list().then((all) => all.map((t) => t.id)),
target: {
mode: 'schema',
url: env.DATABASE_URL,
provision: db, // a client with $executeRawUnsafe — CREATE SCHEMA IF NOT EXISTS
},
}),
])basalt tenant:migrate
# ok acme (tenant_acme)
# FAIL globex (tenant_globex) — <error>
# Done: 1 migrated, 1 failed.With tenancyPlugin, migrate from onMigrate
tenancyPlugin registers its own basalt tenant:migrate, which runs the onMigrate hook. Two commands cannot share a name: the first registered runs, and basalt warns that the other is ignored. In an app with tenancyPlugin, call migrateTenants from its hooks instead of registering tenantMigrateCommand. It reports a failure as ok: false rather than throwing, so throw yourself, or the command reports success:
import { dropTenantSchema, migrateTenants, tenantSchema } from '@basaltkit/prisma'
const target = { mode: 'schema', url: env.DATABASE_URL, provision: db } as const
async function migrateTenant(id: string): Promise<void> {
const [result] = await migrateTenants({ tenants: [id], target })
if (!result?.ok) throw new Error(`Tenant ${id}: ${result?.error ?? 'not migrated'}`)
}
tenancyPlugin({
source: tenants,
onProvision: (tenant) => migrateTenant(tenant.id), // basalt tenant:create
onMigrate: (tenant) => migrateTenant(tenant.id), // basalt tenant:migrate [--tenant=<id>]
onDeprovision: (tenant) => dropTenantSchema(db, tenantSchema(tenant.id)), // basalt tenant:destroy
})The default migrator shells out to prisma migrate deploy with each tenant's scoped connection URL; pass migrate to override it.
Options reference
tenancyPlugin(options):
| Option | Type | Default | Purpose |
|---|---|---|---|
source | TenantSource | — (required) | Where tenant records are loaded from — MemoryTenantSource in dev, tenancy-sqlite/tenancy-prisma (or your own table) in production |
resolvers | TenantResolver[] | — (required) | Authoritative resolvers (subdomain, domain, route, authoritative(fn)) first — an unknown tenant they name resolves to none; fallbacks (header) only when no authoritative resolver named anything. Within each group the first ref that loads a tenant wins |
onConflict | 'precedence' | 'error' | 'precedence' | 'error' runs every resolver and answers 400 TENANCY_CONFLICT when two load different tenants |
servingByDefault | boolean | false | Every tenancy.run() (and the 'tenancy:run' signal) refuses a tenant that is not serving unless the caller passes { serving: false }. Lifecycle paths stay open. See Make it the default |
required | boolean | { except: (string | RegExp)[] } | false | Reject a request that resolved no tenant with 404 TENANCY_NOT_RESOLVED, instead of running it tenant-less. { except } exempts paths (health checks, landing pages) while still guarding the rest |
onMigrate | (tenant) => void | Promise<void> | — | Per-tenant work for basalt tenant:migrate, run inside each tenant's context |
onSeed | (tenant) => void | Promise<void> | — | Per-tenant work for basalt tenant:seed, run inside each tenant's context |
onProvision | (tenant) => void | Promise<void> | — | Brings a NEW tenant's storage into existence, inside its context, from tenancy.create() and basalt tenant:create. Without it a tenant is routable before its schema exists |
onDeprovision | (tenant) => void | Promise<void> | — | Tears that storage down, inside the tenant's context, from tenancy.destroy(). Without it the record goes and the schema stays — schema-per-tenant: dropTenantSchema(db, tenantSchema(tenant.id)) |
canonicalDomain | (tenant) => string | undefined | — | The address a new tenant is reachable at, added to tenant.domains by tenancy.create() before the record is persisted. Without it the domain table stays empty and nothing owns the address |
provision | 'inline' | 'deferred' | 'inline' | 'inline' — create() waits, so the tenant is usable when it returns. 'deferred' — create() returns immediately with status provisioning and the resolver answers 503 until tenancy.provision(id) runs |
validateTenantId | (id: string) => boolean | isValidTenantId | The id grammar tenancy.create() and tenancy.run() enforce (/^[a-z0-9][a-z0-9_-]{0,62}$/, minus global); a rejected id throws InvalidTenantIdError before anything is written, and a resolver ref carrying one resolves to no tenant |
The built-in resolver factories:
| Factory | Option | Type | Default | Purpose |
|---|---|---|---|---|
subdomainResolver({ base }) | base | string | — (required) | The apex your tenants live under. acme.basalt.app → { id: 'acme' }; www, the bare base, and nested subdomains (a.b.basalt.app) are ignored. Authoritative |
domainResolver() | — | — | — | Whole Host → { domain }, resolved through source.findByDomain. For customer-owned domains; requires that method. Authoritative |
headerResolver({ header }) | header | string | 'x-tenant-id' | Reads a request header → { id: <value> }. Change it when your gateway already injects a different header. Fallback (client-controlled) |
routeResolver({ param }) | param | string | 'tenant' | Reads a route param → { id: params.tenant }. For path-based tenancy (/t/:tenant/…). Authoritative |
Every factory returns a plain TenantResolver — (request) => TenantRef | null, with an optional authoritative flag — so a custom one drops into the same array. The Host value is canonicalised (lower-cased, port and trailing dots stripped) before matching, so Victim.com:443 and victim.com. key the same way; a Host outside the hostname grammar (userinfo, path, %, non-ASCII, IP literal) matches nothing.
new CustomDomains(options):
| Option | Type | Default | Purpose |
|---|---|---|---|
store | DomainStore | new MemoryDomainStore() | Where registered domains live — prismaDomainStore(prisma) or sqliteDomainStore(db) in production. A durable implementation must back add() with a UNIQUE constraint and throw DomainTakenError — that insert is the anti-hijack gate (check yours with domainStoreContract from @basaltkit/tenancy/testing) |
now | () => number | Date.now | Injectable clock (tests) |
token | () => string | 24 random bytes, base64url | Verification-token generator (tests) |
resolveTxt | (host) => Promise<string[][]> | node:dns/promises resolveTxt | DNS lookup used by verify(); stub it in tests |
claimTtlMs | number | 72 h | How long an unverified claim holds a domain before another tenant's add() can take it. Verified domains never expire (a stale one yields only to a challenge() record — see reverify()) |
reservedDomains | string[] | [] | The platform's own domains; each one and every subdomain of it is refused with DOMAIN_RESERVED |
challengeSecret | string | — | Enables challenge(tenantId, domain): publishing that TXT record lets the owner's add() take a squatted unverified claim at once. Same value on every instance |
domains.verify(tenantId, domain, { force }) short-circuits on an already-verified domain unless force is set. Run it with force: true on a schedule: a domain whose DNS was later removed or repointed is un-verified on a failed re-check and stops resolving — the defence against dangling-domain takeover.
For a scheduled job, prefer the system-level helpers, which need no tenant id:
schedule.call('reverify-domains', async () => {
const { revoked, errors } = await domains.reverifyAll()
if (revoked.length) log.warn({ revoked }, 'custom domains un-verified')
}).hourly()domains.reverify(domain) re-checks whichever tenant holds the domain and returns { domain, tenantId, status }: valid, revoked (the record is definitively gone — NXDOMAIN, no TXT, or no matching value — so the claim is un-verified), dns-error (a timeout or SERVFAIL: left verified, so a DNS outage never un-verifies every domain at once), unverified, or changed (the record changed hands meanwhile; left alone). reverifyAll() runs it over DomainStore.listVerified() — or over { domains } you pass, for a store without that method — and returns { checked, revoked, errors, results }.
A stale verified claim also yields to the new owner directly: when a domain lapses and someone else buys it, the new owner publishes its challenge(tenantId, domain) record (with challengeSecret set) and calls add(). If that same lookup no longer shows the incumbent's record, the domain is handed over, verified; while the incumbent's record is still published — or the lookup fails — the claim stands and add() throws DOMAIN_TAKEN.
Failure modes & troubleshooting
| Error | Code | HTTP | When |
|---|---|---|---|
TenantRequiredError | TENANT_REQUIRED | 400 | tenantScoped() / requireTenantId() / requireTenant() ran with no tenant in context (and, for requireTenantId, no explicit fallback) |
InvalidTenantIdError | TENANT_ID_INVALID | 400 | tenancy.create(), tenancy.run(), provision(id), destroy(id) (or MemoryTenantSource.create()/save()) with an id outside the tenant-id grammar or a reserved id. Nothing is written |
TenantResolutionConflictError | TENANCY_CONFLICT | 400 | onConflict: 'error' and two resolvers loaded different tenants (e.g. an x-tenant-id that disagrees with the Host) |
TenancyNotResolvedError | TENANCY_NOT_RESOLVED | 404 | required: true and no resolver produced a ref that loaded a tenant |
CentralOnlyRouteError | NOT_FOUND | 404 | A tenant resolved on a route declared meta: { tenant: 'never' }; the body is the plain "route not found" one |
TenantNotFoundError | TENANT_NOT_FOUND | 500 | tenancy.run('unknown-id', …), or forEach() on a TenantSource without list() |
TenantNotReadyError | TENANT_NOT_READY | 503 | A request (or run(…, { serving: true }), see Enter only a serving tenant) resolved to a tenant whose status is provisioning, failed or deleting. 503, not 404: the tenant exists and the client may retry |
TenantSuspendedError | TENANT_SUSPENDED | 403 | A request resolved to a tenant whose status is suspended (or run(…, { serving: true }) was given one). Retrying will not help |
TenantStatusUnknownError | TENANT_STATUS_UNKNOWN | 500 | A request resolved to a tenant whose status tenancy does not recognise (active, a typo). Store ready or no status for a serving tenant |
TenantCreateUnsupportedError | TENANT_CREATE_UNSUPPORTED | 500 | tenancy.create() on a source implementing neither create() nor save() — e.g. one backed by a static config file |
TenantAlreadyExistsError | TENANT_ALREADY_EXISTS | 409 | tenancy.create() (or a source's create()) for an id that already exists. Nothing is written. A failed/provisioning tenant is retried with tenancy.provision(id); an intentional update is source.save() |
TenantNotProvisionableError | TENANT_NOT_PROVISIONABLE | 409 | tenancy.provision() (or basalt tenant:provision) for a suspended or deleting tenant. Nothing runs and the status is kept |
DomainTakenError | DOMAIN_TAKEN | 409 | domains.add() for a domain another tenant registered — verified (and its TXT record still published, or no challenge() record of yours), or unverified and younger than claimTtlMs |
DomainNotFoundError | DOMAIN_NOT_FOUND | 404 | verify / instructions / remove for a domain that isn't registered |
DomainForbiddenError | DOMAIN_FORBIDDEN | 403 | A tenant acted on a domain belonging to a different tenant |
DomainReservedError | DOMAIN_RESERVED | 403 | domains.add() for a domain in reservedDomains or a subdomain of one |
InvalidDomainError | DOMAIN_INVALID | 400 | A domain that is not a hostname (userinfo, path, %, non-ASCII, IP literal) |
MissingCacheScopeError | CACHE_SCOPE_MISSING | 500 | A cache read/write ran with no tenant while tenancy is active — see Caching |
NotATeamMemberError | TEAM_NOT_A_MEMBER | 403 | tenantMembershipPlugin found no membership for the user in the resolved tenant — see Teams |
TENANT_REQUIREDon a background job or a script — there is no resolver outside a request. Wrap the work intenancy.run(tenantId, …), or pass the id explicitly:requireTenantId(job.tenantId).TENANT_REQUIREDon a legitimately central route (sign-up, landing page, platform admin) — those routes shouldn't be callingtenantScoped()at all. Query the central table deliberately, and declaremeta: { tenant: false }on the route rather than looseningrequiredfor the whole app — see the multi-tenant pattern.TENANCY_NOT_RESOLVEDalthough the header/subdomain looks right — the ref resolved but the record didn't load. An unknown subdomain or domain ends resolution — the header is not consulted then — so this is almost always a tenant missing from the source (or, withdomainResolver, a domain that was never verified), or a header sent to a tenant subdomain that names a different tenant. Check withbasalt tenant:list.403 TEAM_NOT_A_MEMBERright after switching tenants — expected, and the point: the tenant resolved, the membership check then refused it. Tenant resolution is identification, never authorization — see Teams.- A custom domain stopped resolving on its own — a scheduled
reverify()/reverifyAll()(orverify(…, { force: true })) re-check failed and un-verified it. Re-publish the_basalt-verify.<domain>TXT record.
Events
| Hook | Payload |
|---|---|
tenancy:switched | { tenant, via } — emitted on every entry into a tenant context, by the HTTP enricher (via: 'http') and by tenancy.run() (via: 'run') |
tenancy:exited | { tenant } — emitted when a tenancy.run() callback settles (resolved or thrown), still inside that tenant's context, so a listener can release what it took on tenancy:switched (prismaPlugin returns its leased client). Not emitted for HTTP requests — an enricher returns a disposer for those |
tenancy:created | { tenant } — emitted once a new tenant is created and provisioned, so a listener may assume its storage exists. Does not fire if onProvision threw |
tenancy:destroyed | { tenant } — emitted by tenancy.destroy() after onDeprovision ran and the record was deleted from the source |
Durable tenant registries and the per-tenant database options are covered in Persistence; the end-to-end sign-up flow is in the multi-tenant SaaS cookbook and Creating a tenant.