Why Iframe Domain Masking Is Broken in 2026 (and How Modern SaaS Actually Handles White-Label URLs)

Was helping someone troubleshoot a "domain masking" setup last week. They had Googled the term, the top result told them to wrap their destination site in an <iframe> on the source domain, the address bar stays put, you're done. They wired it up. Three things broke immediately:

Their React app's window.location.host returned the wrong value, so auth was scoped wrong
Mobile Safari refused to autoplay video inside the frame
Google indexed an empty frame and they lost rank on the content

That's the standard iframe-masking saga in 2026. The advice has been broken for years and it's still what comes up first when you search.

This post: why iframe masking is broken in detail, what to do instead (with working code), the actual use cases where this matters, and how to ship it in one API call.

What "domain masking" is supposed to deliver

You're building a SaaS. Your customer wants their visitors to type shop.acme.com, see your app's content, and have the address bar stay as shop.acme.com for the entire session. Standard white-label requirement.

The product requirement is clear. The wrong implementation is iframe. The right one is server-side reverse-proxy at the edge. Let me show you both.

Why iframes fail (in detail)

SEO is dead

Google indexes pages, not iframes. When a crawler visits shop.acme.com, it sees a page containing an <iframe src="https://yourplatform.com/...">. That's it. The actual content lives behind the frame, on a different hostname.

<!-- What Google sees on shop.acme.com -->
<!DOCTYPE html>
<html>
  <head><title>Loading…</title></head>
  <body>
    <iframe src="https://yourplatform.com/acme" width="100%" height="100%"></iframe>
  </body>
</html>

That's the indexable surface. Indexing splits across two domains, neither ranks well. Your customer's domain shows up in SERPs as an empty page. Your platform domain might rank, but for the wrong URL.

JS context is split

The React app loads inside the iframe. From its perspective, it's running on yourplatform.com, not shop.acme.com:

window.location.host         // "yourplatform.com"
document.cookie              // cookies for yourplatform.com only
window.parent.location.host  // "shop.acme.com" (cross-origin SecurityError on access)

Any code that relies on the hostname (auth scoping, analytics, CSRF tokens, subdomain-based routing) sees the wrong value. Cookies set inside the iframe are third-party cookies, which browsers block by default now. Safari since 2020, Firefox since 2022, Chrome rolling out 2024-2026.

Top-level navigation is broken

Click a link inside the iframe. Without target="_top", it opens inside the frame. Modal dialogs using the full viewport are stuck inside the frame bounds. The browser back button doesn't update the parent URL; hitting back leaves the entire site instead of going to the previous iframe state.

The workarounds (postMessage shims, target attribute on every anchor, custom history API) are a maintenance burden that grows with your app.

Mobile is unreliable

iOS Safari and Chrome on Android have been progressively restricting iframes for security. Things that fail or behave differently inside frames in 2026:

Autoplay video (Safari blocks)
Payment Request API (requires top-level context)
Web Share API (requires top-level context)
Push notification permissions (don't propagate to parent)
Fullscreen API (some platforms restrict)
WebAuthn / Passkeys (require top-level origin)

Your storefront, course platform, or membership site that "worked in iframe" on desktop will quietly fail on a percentage of mobile users. You won't see the bug report because the people who hit it close the tab.

The migration tax is real

Every team I've worked with that shipped iframe masking eventually migrated off it. The reasons stack up. A buyer complains about a broken checkout on iPhone. Google drops a high-value customer's hostname from the index. A new SSO provider refuses to work inside iframes. An auth provider's redirect flow breaks the parent context.

The migration is non-trivial: rewrite every link with target="_top", retrofit cookies to first-party, debug postMessage handshakes, re-verify every payment flow. Four to six weeks of engineering for what should have been done right the first time.

The right approach: reverse-proxy at the edge

Do server-side what iframes were trying to do client-side. The visitor's browser opens a TLS connection to your customer's hostname; that connection terminates at your edge; the edge forwards the request to your origin server-side; the response comes back as a single HTTP document on the customer's hostname.

[ visitor: https://shop.acme.com/products ]
              |
              v  TLS handshake (cert for shop.acme.com)
       [ edge: terminates TLS ]
              |
              v  forwards request to origin
              |   X-Domainee-Original-Host: shop.acme.com
              |   X-Forwarded-Proto: https
              |
       [ your origin: app.yourplatform.com ]
              |
              v  responds with the right tenant's content
              |
       [ edge streams response back to visitor ]
              |
              v
       [ visitor sees: shop.acme.com/products ]

From the browser's perspective, there's a single HTTP document at shop.acme.com. From your origin's perspective, you got a normal request with one extra header telling you the original hostname. From Google's perspective, it crawls shop.acme.com and indexes the real content under that domain.

None of the iframe problems exist. No frame, no split context, no third-party cookies, no broken back button.

How to actually ship it

Three things you need:

A TLS cert for each customer hostname
An edge that terminates TLS and proxies to your origin
Your origin reading X-Forwarded-Host to figure out which tenant the request is for

If you're building this from scratch, most of the work is cert provisioning (Let's Encrypt rate limits, ACME challenge automation, renewal workers) and the multi-region edge. One to three months of platform engineering, then ongoing care forever.

Or you call one API. With Domainee:

$ curl https://api.domainee.dev/v1/domains \
    -H "Authorization: Bearer sk_live_…" \
    -d '{
      "hostname":  "shop.acme.com",
      "originUrl": "https://app.yourplatform.com",
      "mode":      "proxy",
      "keepHost":  true,
      "metadata":  { "tenantId": "acme-42" }
    }'

Two fields that matter:

mode: "proxy" is reverse-proxy mode. Address bar stays on the customer's hostname.
keepHost: true preserves the original Host header forwarding to your origin, so your origin can read which tenant the request is for.

The response gives you a CNAME for the customer to add at their DNS provider. TLS provisions automatically once they save the CNAME. Domain goes live in about a minute.

On your origin side, one piece of middleware:

// middleware.ts
export async function tenantFromRequest(req: Request) {
  const host =
    req.headers.get("x-domainee-original-host") ??
    req.headers.get("host")!;
  const tenant = await db.tenants.findOne({ hostnames: host });
  if (!tenant) throw new Error(`Unknown hostname: ${host}`);
  return tenant;
}

That's most of the integration. Cache the lookup for an hour, invalidate on the domain.created and domain.deleted webhooks.

What changes in your app (vs iframe)

Mostly nothing, which is the point. The browser is genuinely loading shop.acme.com/products as a first-class document. window.location.host returns shop.acme.com. fetch("/api/cart") resolves to shop.acme.com/api/cart (which the edge proxies to your origin). Cookies set on shop.acme.com are first-party. WebAuthn works. Payment Request works. Service workers work.

A few practical things to know.

Absolute URLs in your HTML: links to https://app.yourplatform.com/... land on your platform domain, not the customer's. Usually correct (signup, dashboard, billing portal). Wrong if you meant "current site."

OAuth callbacks: if you initiate OAuth from inside the masked site, the redirect URL needs to be configured for the customer's hostname OR routed through your platform domain. Most teams bounce through the platform domain and return to the customer's after.

Hard-coded CORS origins: if your origin's CORS allowlists https://app.yourplatform.com, requests from https://shop.acme.com fail preflight. Use a dynamic allowlist that accepts any verified customer hostname.

Use cases — who actually needs this

White-label SaaS

Your product is sold by agencies, resellers, or partners. They want their clients to see THEIR domain, not yours. The customer-facing surface (app, storefront, dashboard) lives at the agency's domain; billing and admin stay at yours. See /use-cases/white-label-saas and /use-cases/agencies-platform-builders.

Multi-tenant storefronts

E-commerce platforms in the Shopify / Lemon Squeezy mold. Sellers want shop.theirbrand.com for trust and brand. Stripe Checkout success and cancel URLs return to the seller's domain. Full integration walkthrough at /blog/custom-domains-for-stripe-storefronts.

Course / membership platforms

The school operator runs classes at learn.theirschool.com. Your platform serves the LMS, the URL is theirs. Renewal emails reference their domain. Branded experience end-to-end. See /use-cases/course-platforms.

Creator pages / link-in-bio

Creator brings a vanity domain (bio.creator.com). Your platform renders the page. They get a memorable URL; you keep one app and one deploy. See /use-cases/link-in-bio.

White-label help center / docs

Customer-support and docs platforms where customers want help.theirbrand.com to feel native to their site. See /use-cases/help-centers.

Embedded SaaS / partner integrations

You're embedded inside another company's platform. They want their customers to never leave their domain. Your app lives at app.theirdomain.com even though you serve it.

When NOT to mask

Three cases where masking is the wrong answer:

Rebrands or consolidation. Old domain to new domain. That's forwarding (301), not masking. Different mode in the API. See /domain-forwarding-api.
Campaign URLs. promo.acme.com to acme.com/spring-sale. Also forwarding (302).
Hosting two distinct sites under two hostnames. If the content should differ per hostname AND be independently indexed, you're not masking, you're hosting two real sites. Build two deploys.

For everything else, masking via edge proxy is the move.

Apex domains, WebSockets, streaming

Three things that nominally complicate masking and don't really, in case anyone asks.

Apex domains: acme.com, not shop.acme.com. Apex CNAMEs are technically against spec; most registrars support ALIAS / ANAME / Cloudflare CNAME-flattening. Where they don't, A records work. Domainee returns both options in the dnsRecords response so your UI shows whichever matches the customer's registrar. Full breakdown at /blog/apex-domain-support-for-saas.

WebSockets: fully proxied. Same X-Domainee-Original-Host header on the WS upgrade. Connection lifetime is whatever your origin negotiates.

Streaming responses (chunked, SSE): fully supported. The edge streams responses through without buffering.

TL;DR

If you write a tutorial about domain masking in 2026, please don't recommend iframes. The trade-offs are real and they all break what your user is trying to do.

The right approach is reverse-proxy at the edge: browser sees a real first-class page, Google indexes correctly, cookies are first-party, mobile features work, no JS workarounds.

If you're building from scratch, one to three months of platform work plus ongoing care. If you'd rather skip that, Domainee does it in one API call. 50 customer hostnames free, no card, the first goes live in about a minute.