Multi-Tenancy | AxilJS Docs

Overview

The multi-tenancy middleware resolves, validates, and attaches the current tenant to every incoming request. It supports four resolution strategies and automatically rejects suspended or archived tenants.

Basic Usage

typescript

import { multiTenancy, getTenant, getTenantId } from '@axiljs/cloud'
 
app.use(multiTenancy({
  strategy: 'header',
  headerName: 'x-tenant-id',
  resolveTenant: async (id) => await db.tenants.findById(id),
  required: true,
}))
 
app.get('/api/data', (req, res) => {
  const tenant = getTenant(req)
  res.json({ tenantId: tenant.id, plan: tenant.plan })
})

Resolution Strategies

Strategy	Source	Example
`header`	Configurable request header	`x-tenant-id: acme-corp`
`subdomain`	First segment of the `Host` header	`acme.app.io` → `acme`
`jwt`	`req.locals.user.tenantId` from auth	Populated by `@axiljs/auth`
`custom`	User-supplied async resolver function	Any logic you define

Header Strategy (Default)

typescript

app.use(multiTenancy({
  strategy: 'header',
  headerName: 'x-tenant-id',
}))

Subdomain Strategy

typescript

app.use(multiTenancy({
  strategy: 'subdomain',
  // acme.app.example.com → tenantId = 'acme'
}))

JWT Strategy

typescript

import { authenticate } from '@axiljs/auth'
 
app.use(authenticate(jwt))
app.use(multiTenancy({ strategy: 'jwt' }))
// Reads req.locals.user.tenantId automatically

Custom Strategy

typescript

app.use(multiTenancy({
  strategy: 'custom',
  customResolver: async (req) => {
    const token = req.headers['x-api-key']
    const org = await lookupOrgByApiKey(token)
    return org?.id ?? null
  },
}))

Tenant Validation

The middleware validates tenant ID format and lifecycle status automatically.

typescript

app.use(multiTenancy({
  strategy: 'header',
  validateTenantId: (id) => /^[a-z0-9-]{2,64}$/.test(id),
  resolveTenant: async (id) => {
    const tenant = await db.tenants.findById(id)
    return tenant
  },
}))

Malformed IDs → 401 Unauthorized
Suspended tenants → 401 Unauthorized
Archived tenants → 401 Unauthorized
Unknown tenants → 401 Unauthorized (when required: true)

Helper Functions

typescript

import { getTenant, getTenantId } from '@axiljs/cloud'
 
const tenant = getTenant(req)   // throws if missing
const id = getTenantId(req)     // shorthand for tenant.id

Options Reference

Option	Type	Default	Description
`strategy`	`'header' \| 'subdomain' \| 'jwt' \| 'custom'`	`'header'`	Resolution method
`headerName`	`string`	`'x-tenant-id'`	Header name for header strategy
`resolveTenant`	`(id: string) => Promise<Tenant \| null>`	Identity lookup	Database/cache lookup function
`validateTenantId`	`(id: string) => boolean`	RFC 1123 regex	Custom format validation
`required`	`boolean`	`true`	Reject requests without a tenant
`customResolver`	`(req) => string \| null`	—	Required when strategy is `custom`