npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

better-auth-multi-tenant

v0.7.0

Published

Multi-tenancy for Better Auth by subdomain, custom domain or path: tenant resolution, tenant-bound sessions, and cross-tenant request rejection.

Downloads

1,069

Readme

better-auth-multi-tenant

npm version npm downloads CI License: MIT Types: TypeScript Better Auth npm provenance GitHub stars Follow @patelwees

Multi-tenancy for Better Auth, by subdomain, custom domain or path.

Resolves acme.example.com (or app.acme.com, or example.com/…/t/acme) to a tenant, binds sessions to the tenant they were issued for, and refuses a session that shows up on another tenant.

npm install better-auth-multi-tenant

A runnable Next.js demo lives in examples/nextjs.

Why this exists

Better Auth's official organization plugin gives you organizations, members, roles, invitations and an active-organization field on the session. It does not cover the infrastructure half of multi-tenancy, and says so: subdomain-based tenant resolution, request-scoped isolation and per-tenant callback origins are left to you.

Those are exactly the parts that are easy to get subtly wrong. This plugin handles them, and defaults to failing closed when it is unsure.

It is designed to sit alongside the organization plugin, not replace it. Organizations model who belongs to what; this models which tenant a request is for.

Usage

import { betterAuth } from "better-auth";
import { multiTenant, tenantSessionHooks } from "better-auth-multi-tenant";

export const auth = betterAuth({
  plugins: [
    multiTenant({
      baseDomain: "example.com",
      getTenant: (slug) => db.tenant.findUnique({ where: { slug } }),
    }),
  ],
  // Binds every new session to the tenant it was created on.
  databaseHooks: tenantSessionHooks(),
});

Client:

import { createAuthClient } from "better-auth/client";
import { multiTenantClient } from "better-auth-multi-tenant/client";

export const authClient = createAuthClient({
  plugins: [multiTenantClient()],
});

const { data } = await authClient.multiTenant.current();
// { id: "t_123", slug: "acme", origin: "https://acme.example.com" }

Add the session.tenantId and verification.tenantId columns:

npx @better-auth/cli migrate

verification.tenantId binds codes and tokens to a tenant, see Authentication plugins; pass bindVerifications: false if you do not want that column.

What it does

Tenant resolution. The tenant comes from the request's Host header, so it is decided by DNS and TLS rather than by anything the caller can edit. www, api, app, admin and friends are reserved and never resolve to a tenant.

Cross-tenant rejection. A session carrying tenantId: A that arrives on tenant B's host is refused with 403 CROSS_TENANT_SESSION. A session carrying no tenant at all is refused with 403 UNBOUND_SESSION, since it would otherwise be valid on every tenant. This is the property worth testing in your own suite — see Testing isolation.

Fail closed. requireTenant defaults to requiring a tenant on every path. A route that forgets to opt in returns 400 instead of quietly serving data from whichever tenant it happened to resolve last.

Per-tenant callback origins. tenantOrigin(slug, { baseDomain }) builds the origin a tenant's OAuth flow must return to, so one deployment can serve every subdomain against a wildcard redirect registration instead of a hardcoded apex.

Choosing how tenants are addressed

| Mode | Example | Option | Cookies | Pick it when | | --- | --- | --- | --- | --- | | Subdomain | acme.example.com | baseDomain | Apart by host | Most SaaS apps. Needs wildcard DNS and TLS. | | Custom domain | app.acme.com | getTenantByDomain (with baseDomain) | Apart by host | Customers bring their own domain. You verify ownership. | | Path | example.com/api/auth/t/acme/… | pathPrefix | One name per tenant (tenantCookies) | One host for everyone: no wildcard DNS, an early product, an internal tool. | | Your own | anything on the request | getTenantSlug | Apart by host, or tenantCookies | None of the above fits. |

Set exactly one of baseDomain, pathPrefix and getTenantSlug; the plugin throws at startup otherwise. Session binding, canAccessTenant, the verification binding, teams, SSO, admin and API keys work the same in every mode.

Setup for each mode, the development-only x-tenant header, caching lookups, cookies across subdomains, reverse proxies and edge runtimes are covered in docs/tenancy-modes.md.

Organizations, teams, SSO and admin

With getOrganizationId, each tenant maps to an organization of Better Auth's organization plugin: on a tenant's host only that organization can be active, and organization, invitation, team and admin routes only act on it. With getOrganizationId or getSSODomains, @better-auth/sso only uses the tenant's providers. canAccessTenant decides who may sign in to a tenant. Setup, and what each check covers: docs/organization.md.

Authentication plugins

Better Auth's twoFactor, username, anonymous, phoneNumber, magicLink, emailOTP, passkey (@better-auth/passkey), genericOAuth, oneTap and siwe plugins all work with this plugin, each with end-to-end tests. Their sessions are stamped with the tenant, refused on another and gated by canAccessTenant. In addition, anything a plugin hands out as a verification row (magic-link token, email and phone OTP, two-factor challenge and trusted-device record, passkey challenge, SIWE nonce, OAuth state) is bound to the tenant that issued it: redeeming it on another tenant's host is refused with 403 VERIFICATION_TENANT_MISMATCH (bindVerifications, on by default). A link that is emailed (magic link, OAuth callback) must open on the tenant that sent it, so set tenantBaseURL: true or use a baseURL that follows the request host.

docs/auth-plugins.md has the compatibility table, the answers per plugin, and how to configure a relying party, SIWE domain, Google client id or OAuth redirect per tenant. Gaps that only Better Auth can close are written up in docs/upstream-proposals.md.

Multi-session

With Better Auth's multiSession plugin, /multi-session/list-device-sessions returns only the tenant's sessions, and /multi-session/set-active or /multi-session/revoke with another tenant's session is refused with 403 CROSS_TENANT_SESSION. On subdomains its cookies are host cookies and already apart; this matters when tenants share a host (path mode), where signing in on one tenant no longer signs the same user out of another.

API keys

@better-auth/api-key keys belong to a user or an organization, and users are global, so by default a key made on one tenant works on every other. Set apiKeys: true (and migrate the apikey.tenantId column) to bind each key to the tenant it was created on:

  • A key used as a session (enableSessionForAPIKeys) is refused on another tenant with 403 CROSS_TENANT_SESSION, and a key with no tenant with 403 UNBOUND_SESSION (unless unboundSessions: "allow"). This holds whichever order the two plugins are listed in.
  • On a tenant's host, /api-key/get, list, update and delete only find that tenant's keys; another tenant's key is 404. So does auth.api.verifyApiKey when you pass it the request's headers: another tenant's key comes back valid: false.
  • With getOrganizationId, creating or listing an organization's keys needs the tenant's organization (403 ORGANIZATION_TENANT_MISMATCH).

Keys are stamped in the database, so the binding needs a database row for each key: the plugin's default storage: "database", or "secondary-storage" with fallbackToDatabase: true (the checks read the row, not the cached copy). With secondary storage alone, creating a key on a tenant's host fails with 500 API_KEY_NOT_IN_DATABASE rather than hand out a key bound to nothing. Keys created before you turn it on have no tenant; re-issue them, or set their tenantId. The plugin warns at startup when the api-key plugin is installed and apiKeys is not set.

Device authorization

Better Auth's deviceAuthorization plugin keeps its codes in a deviceCode table of its own, so without binding, a code a user approves on one tenant can be redeemed for a session on another. Set deviceCodes: true (and migrate the deviceCode.tenantId column): each code is stamped with the tenant that issued it, and on a tenant's host /device/token, /device, /device/approve and /device/deny only find that tenant's codes, so another tenant's code is invalid_grant. Codes issued before you turn it on stop working; they expire in minutes anyway. The plugin warns at startup when deviceAuthorization is installed and deviceCodes is not set.

Same email on several tenants

By default a user is global, as in Better Auth: one account per email, usable on every tenant you let them into. Set identity: "tenant" and the same email on two tenants is two separate users, with separate passwords, social accounts, codes and sessions:

multiTenant({ baseDomain: "example.com", getTenant, identity: "tenant" })

Every user and account query is limited to the requesting tenant, and a query outside a tenant's request is refused instead of running across tenants. It needs a migration (a tenantId column, and the unique index on email replaced by one on (tenantId, email)); see Tenant-scoped identity.

OAuth across tenant hosts

Google, GitHub and most providers accept no wildcard redirect URI, so every tenant subdomain or custom domain would have to be registered with each one. Use Better Auth's oAuthProxy with one auth host instead, and tell this plugin which host that is:

import { oAuthProxy } from "better-auth/plugins";

betterAuth({
  plugins: [
    multiTenant({ baseDomain: "example.com", getTenant, oauthProxyHost: "auth.example.com" }),
    oAuthProxy({ productionURL: "https://auth.example.com" }),
  ],
});

Register only https://auth.example.com/api/auth/callback/<provider> with each provider. A sign-in started on acme.example.com (or app.acme.com) goes to the provider, comes back to auth.example.com, and is handed to acme.example.com, where the session is created and bound to acme:

  • auth.example.com names no tenant and serves only the provider callback (/callback/:id); everything else on it answers TENANT_REQUIRED. Keep its label reserved (auth is by default).
  • The hand-off is tied to the OAuth state the starting tenant issued, so replaying it on another tenant fails (error=state_mismatch) and creates no session.
  • The tenant's getTenantPolicy applies to the hand-off as to any OAuth callback.
  • The tenant host must be a trusted origin for oAuthProxy to send the user back there; trustTenantOrigins (on by default) takes care of it.

oAuthProxy proxies the providers in socialProviders (/callback/:id), not genericOAuth (/oauth2/callback/:id). The plugin warns at startup when oAuthProxy has a productionURL and oauthProxyHost is not set.

Per-tenant auth policy

getTenantPolicy decides, per tenant, how users may sign in. It is enforced on the server, so a client that calls a hidden route directly is still refused:

multiTenant({
  baseDomain: "example.com",
  getTenant,
  getTenantPolicy: (tenant) => ({
    methods: tenant.ssoOnly ? ["sso"] : ["email-password", "magic-link", "social:google"],
    signUp: tenant.openSignUp,
    requireTwoFactor: tenant.plan === "enterprise",
  }),
})
  • methods: email-password, username, phone-number, magic-link, email-otp, passkey, sso, siwe, anonymous, social (every social and generic OAuth provider) or social:<id> (one). A route of a method the tenant does not list answers 403 AUTH_METHOD_NOT_ALLOWED, at the start of the flow and on its callback. Leave methods out to allow every method.
  • signUp: false: no new user is created on the tenant by any method (403 SIGN_UP_DISABLED); existing users still sign in.
  • requireTwoFactor: true: a user without the twoFactor plugin turned on gets no session from get-session (so auth.api.getSession in your own code sees none either), and other auth routes answer 403 TWO_FACTOR_REQUIRED. The /two-factor/* enrolment routes and sign-out stay open.
  • /multi-tenant/current returns the tenant's policy so the sign-in page can show only the allowed buttons.

It is called at most once per request; cache it as you would getTenant.

Security notes

On a tenant's host the plugin refuses another tenant's session (cookie or bearer token), verification codes and tokens issued on another tenant, and, with subdomain or custom-domain tenancy, state-changing requests from another tenant's origin. With apiKeys and deviceCodes it does the same for API keys and device codes.

What it does not do:

  • Users are global by default. One account can sign in on every tenant unless you set canAccessTenant, or identity: "tenant" for one user per tenant.
  • Your own queries are not filtered. Scope every data query by tenant yourself.
  • Some plugin state is shared. Usernames, phone numbers, two-factor settings and passkeys belong to the user, and the OAuth provider, oidcProvider, mcp and SCIM plugins are not tenant-scoped.
  • trustProxy is trust you grant. Turn it on only behind a proxy that overwrites X-Forwarded-Host.

The full list, with the trade-offs, is in docs/security.md. Report vulnerabilities privately; see SECURITY.md.

Upgrading from 0.5

0.6.0 refuses some requests 0.5 let through. Each has an option to restore the old behaviour if you depend on it:

| What changes | Error | Restore with | | --- | --- | --- | | With getOrganizationId and the admin plugin, admin routes are scoped to the tenant, and only an owner/admin member of its organization may call them. A platform admin who is not one is refused. | ADMIN_NOT_TENANT_ADMIN, ADMIN_TENANT_MISMATCH | canAdministerTenant (let your staff in), or admin: false | | Admin changes to the global user (password, email, role, ban, removal) refuse a user who belongs to another organization too. | ADMIN_SHARED_USER | adminSharedUsers: "allow" | | create-user / set-role cannot give out an admin role from a tenant's host. | ADMIN_ROLE_NOT_ASSIGNABLE | adminRoleAssignment: "allow" | | A state-changing request from another origin is refused, including a browser extension, or www.acme.com calling acme.com. | CROSS_TENANT_ORIGIN | sameOriginOnly: false | | jwt plugin tokens gain a tenantId claim. | — | jwtTenantClaim: false |

New, opt-in columns: apikey.tenantId (apiKeys: true) and deviceCode.tenantId (deviceCodes: true). Run your migration before turning them on. session.tenantId and verification.tenantId are unchanged from 0.5.

Database per tenant

Better Auth binds one database per instance, so for a database (or Postgres schema) per tenant, createTenantAuth keeps one Better Auth instance per tenant. See docs/database-per-tenant.md.

Options

| Option | Default | Description | | --- | --- | --- | | baseDomain | — | Subdomain tenancy: the apex domain tenants live under, e.g. example.com. Set this, pathPrefix or getTenantSlug. | | pathPrefix | — | Path tenancy: tenants are addressed as <basePath><pathPrefix>/<slug>/…. Mount through withTenantPaths. See Path-based tenants. | | getTenantSlug | — | ({ headers, request, path }) => slug \| null. Your own resolver. See Your own resolver. | | tenantCookies | true with pathPrefix, else false | Give every tenant its own cookie names, and hide other tenants' cookies from the request. | | getTenant | — | (slug) => Tenant \| null. null becomes a 404. | | getTenantByDomain | — | (domain) => Tenant \| null for custom domains outside baseDomain. See Custom domains. | | getOrganizationId | — | (tenant) => organizationId. Locks the active organization on tenant hosts, refuses other organizations' ids and slugs on every /organization/* endpoint, scopes teams and activeTeamId to it, and ties SSO providers to it. See With the organization plugin. | | getSSODomains | — | (tenant) => string[]. Email domains a tenant owns, for SSO providers with no organization. Turns on the SSO checks. See With @better-auth/sso. | | canAccessTenant | — | (user, tenant, { organizationId, adapter }) => boolean. Refuses sessions for users the tenant does not let in (TENANT_ACCESS_DENIED). organizationMembersOnly is a ready one. See Who may sign in to a tenant. | | admin | true with getOrganizationId, else false | Scope the admin plugin to the tenant's members and sessions. true without getOrganizationId throws at startup. See Admin plugin. | | canAdministerTenant | organizationAdminsOnly | (user, tenant, { organizationId, adapter }) => boolean. Who may use the admin plugin on a tenant's host (ADMIN_NOT_TENANT_ADMIN). See Admin plugin. | | adminSharedUsers | "refuse" | "refuse" stops admin routes that change the global user from touching a user who belongs to another organization too (ADMIN_SHARED_USER); "allow" lets them. | | adminRoleAssignment | "refuse" | "refuse" stops create-user and set-role on a tenant's host from giving out the admin plugin's adminRoles (ADMIN_ROLE_NOT_ASSIGNABLE); "allow" lets them. | | jwtTenantClaim | "tenantId" | Claim the jwt plugin's tokens carry the session's tenant in; false leaves tokens alone. Needs jwt({}). | | sameOriginOnly | true | Refuse state-changing requests on a tenant's host from another origin (CROSS_TENANT_ORIGIN). Subdomain and custom-domain tenancy only. | | apiKeys | false | Bind @better-auth/api-key keys to the tenant they were created on (apikey.tenantId). See API keys. | | deviceCodes | false | Bind deviceAuthorization codes to the tenant that issued them (deviceCode.tenantId). See Device authorization. | | teams | true with getOrganizationId, else false | Scope the organization plugin's team routes, list-user-teams and activeTeamId to the tenant's organization. false turns it off; true without getOrganizationId throws at startup. See Teams. | | sso | true with getOrganizationId or getSSODomains, else false | Scope @better-auth/sso to the tenant's providers. false turns it off (no checks, no startup warning); true without either option throws at startup, and so does false with ssoRequireTenantMapping. | | ssoRequireTenantMapping | false | With SSO installed and neither getOrganizationId nor getSSODomains set, true refuses every SSO route on tenant hosts instead of leaving SSO unscoped. | | bindVerifications | true | Stamp the codes, tokens, nonces and challenges that plugins keep as verification rows with the tenant that issued them (verification.tenantId), and refuse redeeming or deleting a live one on another tenant (VERIFICATION_TENANT_MISMATCH). Also drops another tenant's trusted-device cookie before sign-in. Needs the column; false turns it all off. See Authentication plugins. | | revokeScope | "tenant" | "tenant" limits /revoke-sessions, /revoke-other-sessions and /change-password with revokeOtherSessions to the tenant's sessions; "all" ends every session of the user, as Better Auth does. | | reserved | www, api, app, admin, auth, login, static, assets, cdn, mail, docs, status | Subdomains that never resolve. Replaces the default when set. | | slugPattern | DNS label, lowercase | Shape a slug must match. | | allowNestedSubdomains | false | Let acme.eu.example.com resolve to acme. | | allowHeaderOverride | false | Trust a client header to name the tenant. | | headerName | x-tenant | Header consulted when the override is on. | | trustProxy | false | Read the host from X-Forwarded-Host / Forwarded instead of Host: true, a number of proxy hops, or (req) => boolean. See Behind a reverse proxy. | | requireTenant | () => true | Whether a path must carry a tenant. | | enforceSessionTenant | all but auth entry points | Paths where the session's tenant must match the host's. | | getSessionTenantId | session.session.tenantId | How to read a session's tenant. | | unboundSessions | "reject" | "allow" lets sessions with no tenant through. Use only while migrating. | | protocol | "https" | Protocol of the origin returned by /multi-tenant/current. | | port | — | Port of the origin returned by /multi-tenant/current. | | trustTenantOrigins | true | Trust the requesting tenant's own subdomain or custom domain without listing it in trustedOrigins. Never another tenant's. | | identity | "global" | "tenant": the same email on two tenants is two users. Scopes user and account queries to the requesting tenant; needs a migration. See Same email on several tenants. | | oauthProxyHost | — | The host of oAuthProxy's productionURL. It serves the provider callback without a tenant and hands the profile to the starting tenant. See OAuth across tenant hosts. | | getTenantPolicy | — | (tenant) => ({ methods?, signUp?, requireTwoFactor? }). Per-tenant allowed sign-in methods, sign-up and required 2FA, enforced on the server. See Per-tenant auth policy. | | tenantBaseURL | false | Build baseURL from the tenant's host per request, so emailed links and OAuth redirect URIs use its subdomain or custom domain. Changes jwt iss/aud and the redirect URIs providers must accept. | | onTenantResolved | — | Called after each successful resolution. |

cacheTenantLookup(lookup, { ttl, maxSize?, cacheMisses? }) wraps getTenant or getTenantByDomain with an in-memory cache; see Caching tenant lookups.

Additional options of createTenantAuth (it also takes every option above except requireTenant). See Database per tenant.

| Option | Default | Description | | --- | --- | --- | | createAuth | — | (tenant) => BetterAuthOptions. Builds a tenant's instance, with its own database. | | maxSize | unbounded | Most instances cached; the least recently used is evicted beyond it. A positive integer. | | onEvict | — | (tenant, auth) => void. Called when an instance leaves the cache; close its connections here. | | basePath | "/api/auth" | With pathPrefix: where the instances are mounted, used to find the tenant in the URL and given to every instance. |

Error codes

| Code | Status | Meaning | | --- | --- | --- | | TENANT_REQUIRED | 400 | The path needs a tenant and the request did not name a valid one (host, path prefix or getTenantSlug). Always, with createTenantAuth. | | INVALID_FORWARDED_HOST | 400 | trustProxy is on and the forwarded host is malformed, disagrees between X-Forwarded-Host and Forwarded, or has fewer entries than the trusted hops. | | TENANT_NOT_FOUND | 404 | getTenant (or getTenantByDomain) returned null. Same for createTenantAuth, before any instance is created. | | TENANT_INACTIVE | 403 | The tenant's status is not "active". | | CROSS_TENANT_SESSION | 403 | The session belongs to a different tenant, or /revoke-session named another tenant's session. | | UNBOUND_SESSION | 403 | The session carries no tenant id (see unboundSessions). | | TENANT_ACCESS_DENIED | 403 | canAccessTenant did not let the user in; no session was created. | | AUTH_METHOD_NOT_ALLOWED | 403 | The tenant's policy does not allow this sign-in method (getTenantPolicy). | | SIGN_UP_DISABLED | 403 | The tenant's policy turns sign-up off; no user was created. | | TWO_FACTOR_REQUIRED | 403 | The tenant requires two-factor authentication and the user has not turned it on. | | ORGANIZATION_TENANT_MISMATCH | 403 | /organization/set-active tried to activate (or clear) an organization other than the tenant's, or an organization, team, invitation or member route named another organization's (see getOrganizationId). | | ADMIN_TENANT_MISMATCH | 403 | An admin plugin route named a user who is not a member of the tenant's organization (see admin). | | ADMIN_NOT_TENANT_ADMIN | 403 | The caller of an admin plugin route does not administer the tenant (see canAdministerTenant). | | ADMIN_SHARED_USER | 403 | An admin route that changes the global user named a user who also belongs to another organization (see adminSharedUsers). | | ADMIN_ROLE_NOT_ASSIGNABLE | 403 | create-user or set-role on a tenant's host tried to give out one of the admin plugin's adminRoles (see adminRoleAssignment). | | CROSS_TENANT_ORIGIN | 403 | A state-changing request came from another host's page (see sameOriginOnly). | | TEAM_TENANT_MISMATCH | 403 | A team route or activeTeamId named a team of another tenant's organization. | | VERIFICATION_TENANT_MISMATCH | 403 | A code, token, nonce, challenge or pending cookie was issued on a different tenant, or carries no tenant stamp (see bindVerifications). | | SSO_PROVIDER_TENANT_MISMATCH | 403 | An SSO sign-in, registration, callback, SAML response or provider route reached a provider that does not belong to the tenant, or a SAML RelayState that was not handed out on this tenant (see getSSODomains, ssoRequireTenantMapping). |

Reading the tenant in your own code

requireTenantFromContext returns the tenant resolved for the request, or throws 400 TENANT_REQUIRED when there is none — so a path exempted by requireTenant fails closed instead of crashing on null:

import { createAuthEndpoint } from "better-auth/api";
import { requireTenantFromContext } from "better-auth-multi-tenant";

createAuthEndpoint("/projects", { method: "GET" }, async (ctx) => {
  const { tenant } = requireTenantFromContext(ctx.context);
  return ctx.json(await db.project.findMany({ where: { tenantId: tenant.id } }));
});

getTenantFromContext is the non-throwing variant and returns null instead.

Reading the tenant on the client

getTenant(client) calls /multi-tenant/current through your Better Auth client and never throws. It returns { tenant, error }, where error.code is typed to the plugin's error codes. It is framework-free, so it works in Vue, Svelte or a plain script:

import { getTenant } from "better-auth-multi-tenant/client";

const { tenant, error } = await getTenant(authClient);
if (error?.code === "TENANT_NOT_FOUND") showUnknownWorkspacePage();

For React, useTenant(client) in better-auth-multi-tenant/react returns { tenant, error, isPending } (react 18 or newer is an optional peer dependency). It fetches in an effect, so server rendering produces the pending state, and it starts over if you pass a different client:

import { useTenant } from "better-auth-multi-tenant/react";

function Brand() {
  const { tenant, error, isPending } = useTenant(authClient);
  if (isPending) return null;
  if (error?.code === "TENANT_NOT_FOUND") return <NotFound />;
  return <h1>{tenant?.slug}</h1>;
}

error.status is 0 when no usable response arrived (network failure, or a body that is not the plugin's).

Compatibility

Each framework has a minimal example under examples/ that installs the packed package (not the source), runs two tenants on *.localhost, and has a smoke test: sign up on acme, replay the cookie on globex, expect 403 CROSS_TENANT_SESSION. The Examples workflow runs every one on each push and pull request.

| Framework | Runtime | Tested version | Better Auth integration | Status | | --- | --- | --- | --- | --- | | Hono | Node 22 | hono 4.13.13, @hono/node-server 2.1.5 | auth.handler(c.req.raw) | Passing | | Express | Node 22 | express 5.3.0 | toNodeHandler (better-auth/node) | Passing | | Next.js | Node 22 (next start) | next 16.4.2, react 19.3.1 | route handler calling auth.handler(request) | Passing | | Nuxt | Node 22 (Nitro) | nuxt 4.6.2 | auth.handler(toWebRequest(event)) | Passing | | SvelteKit | Node 22 (adapter-node) | @sveltejs/kit 3.1.0 | svelteKitHandler (better-auth/svelte-kit) | Passing | | TanStack Start | Node 22 (Vite dev server) | @tanstack/react-start 1.169.3 | server route handlers calling auth.handler(request) | Passing | | Cloudflare Workers | workerd via wrangler dev --local | wrangler 4.151.3, hono 4.13.13 | auth.handler(c.req.raw) | Passing |

All use Better Auth 1.7.14. The examples keep users in memory and hardcode the tenant list; swap in your own database and getTenant lookup. TanStack Start is exercised on its dev server, and Workers on the local workerd simulator, not on a deployed Worker.

To run one yourself, see its README; the short version is npm run pack:examples, then npm install --no-package-lock --legacy-peer-deps && npm run smoke inside the example.

Scope

Tenant resolution (subdomain, custom domain, path or your own), session binding, cross-tenant rejection and callback origins are implemented and tested, as is scoping for the organization, admin, multi-session, SSO and API key plugins. Query-level data isolation helpers and per-tenant OAuth provider configuration are not in this release.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Found a way to cross a tenant boundary? Please report it privately, as described in SECURITY.md, rather than in a public issue.

Contact

Questions, feedback or something to show off? Message or tag the maintainer on X, @patelwees, send a Discord message to weespatel, or connect on LinkedIn. Bugs still belong in GitHub issues, and security reports go through SECURITY.md, not public posts.

License

MIT