--- title: "Laravel Multi-Tenancy with Subdomains" description: "A Laravel multi-tenancy subdomain guide for stancl/tenancy: identification middleware, central domains, tenant routes, sessions, wildcard DNS and links." date: 2026-09-29 author: erag category: multi-tenancy tags: [Multi-tenancy, Routing] pageClass: blog-page --- # Laravel Multi-Tenancy with Subdomains: How Tenant Identification Works Most multi-tenant Laravel apps give each customer their own address, like `acme.your-saas.com`. A Laravel multi-tenancy subdomain setup looks simple from the outside, but a surprising number of pieces have to agree with each other: the identification middleware, the list of central domains, the `domains` table, your routes, session cookies, DNS and the way you build links. When one of them is off, you usually get a confusing 404 or a server error rather than a helpful message. We'll go through each piece using [stancl/tenancy](https://tenancyforlaravel.com) (version 3), the package behind most Laravel multi-tenant apps. If you haven't settled on a data model yet, read [how to build a multi-tenant SaaS with Laravel](/blog/multi-tenant-saas-laravel-database-per-tenant.html) first. ## How subdomain identification works Before your controller runs, every request goes through the same steps: ```text acme.your-saas.com/dashboard → is the host a central domain? no → look up the host in the domains table → tenant "acme" → tenancy()->initialize($tenant) (database, cache, files, queue switch) → your route runs inside the tenant ``` When the host is a central domain (`your-saas.com`), tenancy isn't started. Your central app handles the request instead, which covers the marketing site, sign-up and the platform admin. ## Laravel multi-tenancy subdomain middleware: which one to use stancl/tenancy ships three middleware that read the host name. The difference between them is what they look up in the `domains` table. | Middleware | Looks up | Store in `domains.domain` | | --- | --- | --- | | `InitializeTenancyByDomain` | The full host, e.g. `acme.your-saas.com` | `acme.your-saas.com` | | `InitializeTenancyBySubdomain` | Only the first part of the host, e.g. `acme` | `acme` | | `InitializeTenancyByDomainOrSubdomain` | The subdomain if the host ends with a central domain, otherwise the full host | `acme` for subdomains, `app.customer.com` for custom domains | `InitializeTenancyBySubdomain` throws a `NotASubdomainException` when the host is a central domain, a bare `localhost`, an IP address, or a domain that doesn't end with one of your central domains. By default it treats the first part of the host as the subdomain. If you prefix hosts with `www`, the static `$subdomainIndex` property lets you change that. Our preference is to store the **full host** with `InitializeTenancyByDomain`. It's the most explicit option: each row in the `domains` table is exactly the host a browser sends, so nothing is guessed, and moving to a different central domain later means updating rows rather than changing code. ## Configure the central domains The package has to know which hosts are not tenants. That's the `central_domains` key in `config/tenancy.php`: ```php // config/tenancy.php 'central_domains' => [ env('APP_DOMAIN'), // e.g. your-saas.com ], ``` By default, the published config lists `127.0.0.1` and `localhost`. Replace them with your real central domain. If you don't, your production host gets treated as a tenant and returns an error. The middleware compare the request host exactly, so `your-saas.com` and `www.your-saas.com` need two separate entries. ## Split routes: routes/tenant.php vs routes/web.php Running `php artisan tenancy:install` creates `routes/tenant.php`, and the generated `TenancyServiceProvider` loads it. Tenant routes carry two middleware: ```php // routes/tenant.php Route::middleware([ 'web', InitializeTenancyByDomain::class, PreventAccessFromCentralDomains::class, ])->group(function () { Route::get('/dashboard', DashboardController::class)->name('dashboard'); }); ``` `PreventAccessFromCentralDomains` aborts with a 404 when someone opens a tenant route on a central domain. Your central routes stay in `routes/web.php`, and they need protecting from tenant hosts as well. stancl's documentation suggests wrapping them in `Route::domain()` for each central domain. A small middleware that aborts when the host isn't in `central_domains` does the job just as well, and it's what we tend to use. ### Unknown subdomains A request for `typo.your-saas.com` throws `TenantCouldNotBeIdentifiedOnDomainException`, and unless you handle it, the visitor sees a server error. Turn it into a 404 in `bootstrap/app.php`: ```php use Stancl\Tenancy\Contracts\TenantCouldNotBeIdentifiedException; ->withExceptions(function (Exceptions $exceptions): void { $exceptions->render(function (TenantCouldNotBeIdentifiedException $e) { abort(404); }); }) ``` ## The domains table The package's migration creates a central `domains` table with a unique `domain` column and a `tenant_id` foreign key that cascades on delete. A tenant can have more than one domain: ```php $tenant = Tenant::create(); $tenant->domains()->create(['domain' => 'acme.your-saas.com']); ``` On save, the `Domain` model lowercases the domain and checks that it doesn't already belong to another tenant. If it does, you get a `DomainOccupiedByOtherTenantException`. When customers pick their own subdomain, catch that exception and show it as a validation error. You should still validate the subdomain yourself before it gets that far. Allow lowercase letters, digits and hyphens, cap each DNS label at 63 characters, and keep a list of reserved names such as `www`, `api` or `admin`. ## Sessions and cookies across subdomains In a multi-tenant app, leave `SESSION_DOMAIN` empty (`null`). The session cookie is then a **host-only** cookie. `acme.your-saas.com` and `globex.your-saas.com` each get their own session, and signing in to one tenant never signs you in to another. With `SESSION_DOMAIN=.your-saas.com`, one cookie is shared across every subdomain. That's handy for a single app spread over subdomains, but here it mixes tenant sessions together. Laravel's `XSRF-TOKEN` cookie uses the same domain setting, so it would be shared too. ::: tip Sessions in tenant databases If you use the database session driver together with the database bootstrapper, sessions started on a tenant host are stored in that tenant's database. That's one more reason a cookie shared across tenants wouldn't work. ::: ## Generating links to a tenant's subdomain `route()` builds URLs for the current host. So from the central admin, `route('dashboard')` points at `your-saas.com`, not at the tenant. There are two ways around this. The first is the `tenant_route()` helper that comes with stancl/tenancy. It swaps the host of a generated URL: ```php $url = tenant_route('acme.your-saas.com', 'dashboard'); // https://acme.your-saas.com/dashboard ``` The second is to build the URL yourself from a relative path. We like this one because it also works for signed links: ```php $path = URL::temporarySignedRoute('invitation.show', now()->addDays(7), [], absolute: false); $url = "https://{$tenant->domains()->value('domain')}{$path}"; ``` On the tenant route, validate relative signed URLs with the `signed:relative` middleware. There's a fuller walkthrough of this pattern in [our post on user invitations with signed URLs](/blog/laravel-user-invitations-signed-urls.html). ## Wildcard DNS and TLS in production A new tenant should work the moment it's created, without anyone touching DNS or the server. For that you need the following: | Layer | What to set up | | --- | --- | | DNS | A wildcard record `*.your-saas.com` pointing at your server, next to the record for `your-saas.com` | | Web server | A virtual host that serves both, e.g. nginx `server_name your-saas.com *.your-saas.com;` | | TLS | A wildcard certificate for `*.your-saas.com`. Let's Encrypt issues wildcards only through the DNS-01 challenge | Keep in mind that a wildcard certificate only covers one level. `acme.your-saas.com` is covered; `eu.acme.your-saas.com` isn't. If you turn on Laravel's trusted hosts, calling `$middleware->trustHosts()` without arguments trusts the host of `APP_URL` and all of its subdomains. It's skipped in the `local` environment. ## Local development You need wildcard subdomains on your laptop as well, and `/etc/hosts` can't do wildcards. Our [guide to local subdomains with Laravel Herd](/blog/laravel-herd-subdomains.html) covers Herd, the alternatives and the usual pitfalls. ## Frequently asked questions ### Should I store the full domain or only the subdomain? That depends on the middleware. `InitializeTenancyByDomain` looks up the full host, while `InitializeTenancyBySubdomain` only looks up the first part. We'd store full hosts: it's the most explicit option and it leaves room for other domains later. ### Why do I get a 404 on my central domain? There are two usual causes. Either a tenant route is being opened on a central host, which `PreventAccessFromCentralDomains` blocks on purpose, or your host is missing from `central_domains`. Check that `APP_DOMAIN` matches the host in the browser exactly. ### Can users stay logged in across tenant subdomains? Only with a shared `SESSION_DOMAIN`, and we don't recommend that for multi-tenant apps. Each tenant should have its own session, with users signing in to each tenant separately. ### Can tenants also use their own custom domain? Yes. A custom domain is just another row in the `domains` table, identified by `InitializeTenancyByDomain` or `InitializeTenancyByDomainOrSubdomain`. The customer points their domain at your server, and you need a TLS certificate for each custom domain. ## How SaaS Laravel handles subdomains This is the setup we ship in the [SaaS Laravel starter kits](/). `APP_DOMAIN` is the only central domain, and tenant domains are always `.APP_DOMAIN`, stored as full hosts. A global middleware skips tenancy on the central domain and runs `InitializeTenancyByDomain` everywhere else. Unknown hosts return a 404, and a `central.only` middleware keeps the central admin off tenant hosts. `SESSION_DOMAIN` stays `null`, and invitation and password-reset links are built from the tenant's primary domain. Each tenant can have several subdomains with their own app name, language and auth features. The [Domains](/docs/core/domains.html) and [Multi-tenancy](/docs/core/multi-tenancy.html) docs have the details.