---
title: Usage inside an iframe
description: Embed your website in an iframe with secure session management and custom storage handlers.
sidebar:
  order: 60
---

## Overview

If your website can embed in an iframe that other websites consume, update your configuration based on this guide.


## Before you start

If the sites where your iframe can embed share the same top-level domain as the iframe domain, then you can ignore this section.


## Steps

### 1. Update the frontend configuration

- Set `isInIframe` to `true` during `Session.init` on the frontend.
- You need to use `https` during testing / `dev` for this to work. You can use tools like [ngrok](https://ngrok.com/) 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` to ensure that the app works on safari and chrome incognito. These handlers 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 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`)](https://github.com/SuperTokens/supertokens-auth-react/blob/master/examples/with-next-iframe/config/windowHandler.js) and [here (`cookieHandler`)](https://github.com/SuperTokens/supertokens-auth-react/blob/master/examples/with-next-iframe/config/cookieHandler.js).

<UITypeSwitch />

<VariantContent storageKey="ui-type" value="prebuilt">

<DependentContent passive group="frontend-prebuilt-ui">
<ContentOption title="Angular" value="angular">
You need to make changes to the auth route configuration, as well as to the `supertokens-web-js` SDK configuration at the root of your application:

This change is in your auth route configuration.
</ContentOption>
</DependentContent>

<CodeGroup group="frontend-prebuilt-ui">
<Tab title="Reactjs" value="reactjs">
```tsx check=false reason="Requires SDK globals from surrounding application"
import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    Session.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});
```
</Tab>
<Tab title="Angular" value="angular">
```tsx check=false reason="Requires SDK globals from surrounding application"
supertokensUIInit({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    supertokensUISession.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});
```
</Tab>
</CodeGroup>

<DependentContent passive group="frontend-prebuilt-ui">
<ContentOption title="Angular" value="angular">
This change goes in the `supertokens-web-js` SDK configuration at the root of your application:
</ContentOption>
</DependentContent>

<CodeGroup passive group="frontend-prebuilt-ui">
<Tab title="Angular" value="angular">
```tsx check=false reason="Requires SDK globals from surrounding application"
import SuperTokens from "supertokens-web-js";
import Session from "supertokens-web-js/recipe/session";

SuperTokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
  },
  recipeList: [
    Session.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});
```
</Tab>
</CodeGroup>

</VariantContent>

<VariantContent storageKey="ui-type" value="custom">



<DependentContent passive group="frontend-custom-ui">
<ContentOption title="Mobile" value="mobile">
:::warning[Not applicable to mobile apps]
:::
</ContentOption>
</DependentContent>

<CodeGroup group="frontend-custom-ui">
<Tab title="Web" value="web">
<DependentContent group="install-method" label="Installation method">
<ContentOption title="npm" value="npm">
```tsx check=false reason="Requires SDK globals from surrounding application"
import SuperTokens from "supertokens-web-js";
import Session from "supertokens-web-js/recipe/session";

SuperTokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
  },
  recipeList: [
    Session.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});
```
</ContentOption>
<ContentOption title="Script tag" value="script-tag">
```tsx check=false reason="Requires SDK globals from surrounding application"
supertokens.init({
  cookieHandler,
  windowHandler,
  appInfo: {
    apiDomain: "...",
    appName: "...",
  },
  recipeList: [
    supertokensSession.init({
      tokenTransferMethod: "header",
      isInIframe: true,
    }),
  ],
});
```
</ContentOption>
</DependentContent>
</Tab>
<Tab title="Mobile" value="mobile">

</Tab>
</CodeGroup>



</VariantContent>

:::warning[Because of the restrictions on access to storage on Chrome incognito, you must use 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 logs out.]
:::