36 lines
1.2 KiB
Markdown
36 lines
1.2 KiB
Markdown
|
---
|
||
|
|
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.
|