---
id: ADR-0005
title: Share one API host across storefront subdomains
status: active
date: 2026-08-20
supersedes: [ADR-0004]
tags: [architecture, multi-tenant, api, routing, dns]
---

# ADR-0005: Share one API host across storefront subdomains

## Context

One frontend bundle serves a base storefront domain and tenant subdomains. The
API is shared at the base-domain level; a tenant subdomain must not create a
nested API hostname.

## Decision

- `example.com`, `store1.example.com`, and `www.example.com` all use
  `https://api.example.com`.
- The complete storefront hostname remains the tenant hint. nginx validates the
  browser Origin and forwards that hostname as `X-Storefront-Host`.
- Backend tenant lookup trusts that header only from the known proxy, verifies
  it against the domain registry, and binds authenticated sessions to the same
  tenant.
- Localhost continues through `/api`. `tenantApiBaseUrls` remains available for
  public-suffix or custom-domain exceptions.

## Consequences

Tenant subdomains need no extra API DNS records or certificates. CORS must echo
the exact allowed storefront origin, while unknown or disabled domains still
receive `403` from the backend. The shared API `Host` alone cannot identify a
subdomain tenant.