Troubleshooting

Most integration problems fall into a handful of categories. Work top-down: the checks are ordered from most to least common.

The iframe is blank

1. CSP is blocking it. Open the browser console. A message like "Refused to frame … because it violates … frame-src" means your Content Security Policy does not list the EmbedAuth origin. Add it to frame-src and reload.
2. The origin isn't allowed. The embed refuses to run on origins you have not registered. Confirm the exact origin of the hosting page (scheme + host + port) is in your app's Allowed origins in the dashboard. http://localhost:3000 and http://127.0.0.1:3000 are different origins.
3. Wrong clientId. A typo in the iframe src yields a frame that cannot initialize. Copy the clientId directly from the dashboard.

I never receive postMessage events

1. The origin check is rejecting them. The most common bug is comparing against the wrong origin string. event.origin has no trailing slash and no path — and for a widget embedded on your site it is https://cdn.embedauth.com, because the embedauth.com/embed/… URL redirects there. Log event.origin once to confirm the literal you compare against matches.
2. The listener was added too late or removed too early. In SPAs, make sure addEventListener('message', …) runs before the user can complete the form, and that your cleanup (removeEventListener) is not firing on every render. The React and Vue guides show correct lifecycle handling.
3. You have multiple listeners fighting. If you mount the embed component twice, each instance adds a listener. De-duplicate or scope them.

Cookie / "works then immediately logs out" problems

This almost always means you are relying on a cookie set inside the iframe, which modern browsers block across sites. EmbedAuth is designed so you do not need that: authentication returns a token by message, and you establish your own first-party session from it. If you are trying to read an EmbedAuth cookie from your page, stop — take the token from authframe:auth-success, verify it on your server, and set your own httpOnly session cookie. The Next.js guide shows the full pattern.

OAuth returns an error or a blank page

1. Redirect URI mismatch. The redirect URI registered with the OAuth provider (Google, GitHub, …) must match exactly what EmbedAuth uses, including scheme and trailing path. A mismatch is the number-one cause of redirect_uri_mismatch.
2. Pop-up blocked. If OAuth opens in a pop-up, browser pop-up blockers can suppress it when it is not triggered by a direct user click. Ensure the provider button is a genuine user gesture.
3. redirect not in the allow-list. If you pass a post-auth redirect URL parameter, it must be registered in the app's allowed redirects or it will be refused.

Token verification fails on my server

Language-specific verifier code and error tables are in the Node.js, Python, and Go guides.

The frame has an inner scrollbar

You are not handling authframe:resize. Listen for it and apply data.height to the iframe element so it grows with the form. See the resize helper in the React guide.

Still stuck?

Collect the browser console output, the exact origin of your hosting page, and your clientId, then reach out through the contact page. Those three details resolve the large majority of cases immediately.