Organization Slug & Subdomain Routing

Starting in v1.0.9, the platform includes a Next.js middleware layer that automatically resolves the active organization from every incoming request. This makes true multi-tenant routing possible from a single shared deployment.

How It Works

The middleware intercepts all requests before they reach any route handler, page, or API endpoint. It inspects the request to determine which organization the request belongs to, then injects that context into the request's headers so downstream code can read it without performing additional lookups.

Organization resolution is attempted via two strategies, in order:

1. Subdomain Routing

If the incoming hostname matches the pattern <slug>.platform.com, the slug is extracted from the subdomain.

Example:

https://acme.platform.com/dashboard
→ resolves org slug: acme

This is the preferred routing strategy for production environments. It provides clean, branded URLs for each organization.

Infrastructure requirement: Your DNS and reverse proxy must be configured with a wildcard subdomain record (e.g. *.platform.com) pointing to the platform.

2. Path-Prefix Routing

If no subdomain is present (or the request arrives on a bare domain), the middleware checks for a /org/<slug> path prefix.

Example:

https://platform.com/org/acme/dashboard
→ resolves org slug: acme

This strategy requires no special DNS configuration and works in any environment, including local development and shared staging deployments.

Injected Request Headers

Once the organization is resolved, the middleware injects the org context into the request headers before passing the request downstream. Server components, API route handlers, and other middleware can read this header to identify the current tenant without re-parsing the URL.

Header	Description
`x-org-slug`	The resolved organization slug (e.g. `acme`)

Example usage in a Next.js API route or server component:

import { headers } from 'next/headers';

const orgSlug = headers().get('x-org-slug');
// → 'acme'

Multi-Tenant Architecture

This middleware is the foundation of the platform's multi-tenancy model. Key properties:

Single deployment — All organizations are served from one codebase and one deployment. No per-tenant infrastructure is required.
Zero configuration per tenant — Adding a new organization does not require code changes, new deployments, or routing rule updates.
Consistent context propagation — Because org identity is resolved at the middleware layer and injected as a header, all downstream code has a uniform way to access tenant context regardless of which routing strategy was used.

Local Development

For local development, subdomain routing requires editing your /etc/hosts file to map test subdomains to localhost. Alternatively, use path-prefix routing, which works without any host configuration:

http://localhost:3000/org/acme/dashboard

Routing Strategy Comparison

Strategy	URL Example	DNS Required	Best For
Subdomain	`acme.platform.com/dashboard`	Wildcard DNS (`*.platform.com`)	Production, branded experiences
Path prefix	`platform.com/org/acme/dashboard`	None	Local dev, staging, simple deployments