Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Which UI do you use?
Custom UI
Pre built UI

Using in an iframe

If your website can be embedded in an iframe which is consumed by other websites, then this section is for you.


If the sites in which your iframe can be embedded share the same top level domain as the iframe domain, then you can ignore this section.

Frontend changes#

  • Set isInIframe to true during Session.init on the frontend.
  • You will need to use https during testing / dev for this to work. You can use tools like ngrok to create a dev env with https on your website / API domain.
  • Switch to using header based auth
  • Provide a custom windowHandler and a custom cookieHandler which will make sure that the app works on safari and chrome incognito. These handlers will switch from using document.cookies to localstorage to store tokens on the frontend (since safari doesn't allow access to document.cookies in iframes), and will use in memory storage for chrome incognito (since chrome incognito doesn't even allow access to localstorage). You can find implementations of these handlers here (windowHandler) and here (cookieHandler).
import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";

appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "..."
recipeList: [
tokenTransferMethod: "header",
isInIframe: true

Because of the restrictions on access to storage on Chrome incognito, we are forced to use an in memory storage to store the tokens on the frontend. This in turn implies that if the user refreshes the page, or if your app does a full page navigation, the user will be logged out.

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI