How EmbedAuth Works
The architecture behind embedded authentication — the iframe boundary, postMessage handshake, RS256 tokens, and why third-party cookies never enter the picture.
EmbedAuth is built around one idea: your users authenticate on our origin, inside an iframe, and your page only ever receives a signed token — never a password, never a session cookie it has to manage. Understanding this boundary explains almost every design decision and every configuration step.
The three parties
Three trust domains are involved: the user, your application (page + server), and EmbedAuth. The credentials only ever exist between the user and EmbedAuth. Your application's job is reduced to accepting a token and deciding whether to trust it.
Why an iframe?
An iframe creates a separate browsing context with its own origin. That isolation buys three things:
- Credential isolation. Passwords, OTP inputs, and OAuth redirects happen on
embedauth.com, not on your origin. A vulnerability in your marketing site's JavaScript cannot read what the user types into the auth form. - A single, audited surface. Every EmbedAuth customer shares the same hardened auth implementation. Security fixes ship once, for everyone.
- No cookie juggling on your side. Your page never sets or reads an auth cookie. It receives a token by message and forwards it to your API.
The trade-off is that iframes and cross-origin communication have real constraints — which is exactly what the rest of the docs help you navigate. If you want the deeper background on those constraints, the blog article Why iframe Authentication Is Difficult covers them.
The postMessage handshake
Cross-origin frames cannot call each other's functions, so they exchange structured messages via window.postMessage. EmbedAuth emits a small set of typed events — auth-success, auth-error, mode-change, resize, and loaded. Your page subscribes with a single message listener.
The security rule is non-negotiable: verify event.origin before you read event.data. Any page can post a message into your window; only messages from the EmbedAuth origin are trustworthy. Full event payloads are documented in PostMessage Events.
Why third-party cookies don't matter here
Browsers have spent years restricting third-party cookies — Safari's ITP, Chrome's Privacy Sandbox — and these restrictions break auth systems that rely on a cookie set inside an iframe. EmbedAuth sidesteps the problem entirely: the result of authentication is a token passed by message, not a cookie the browser must attach to future cross-site requests. Because nothing depends on third-party cookie access, nothing breaks when browsers tighten those rules.
Why RS256 instead of a shared secret
EmbedAuth signs tokens with RS256, an asymmetric algorithm. There is a private signing key (held by EmbedAuth) and a public verification key (published at the JWKS endpoint). The consequences:
- Your backend needs no secret to verify tokens. It fetches the public key and caches it.
- You can verify tokens in a browser extension, an edge function, or any number of microservices without distributing a secret to each.
- Key rotation is transparent: EmbedAuth can publish a new key, and clients that use a standard JWKS library pick it up by
kidautomatically.
If you have only ever used HMAC (HS256) tokens, the mental shift is that verification and signing use different keys. The blog post JWT Explained for Developers walks through the format in detail.
Where your session begins
EmbedAuth authenticates the user and proves who they are. What happens next is yours to own. Most applications, on receiving a verified token, mint their own first-party session — a cookie or token scoped to your API — and treat the EmbedAuth token as a short-lived proof of identity rather than a long-lived credential. This keeps your session lifetime, revocation, and refresh policy under your control.