---
title: Share sessions across sub domains
description: Configure SuperTokens to share sessions across multiple subdomains.
sidebar:
order: 40
---
## Overview
Configure sharing sessions across multiple subdomains in SuperTokens by setting the `sessionTokenFrontendDomain` attribute of the Session recipe in your frontend code.
:::info[Example]
- Your app has two subdomains `abc.example.com` and `xyz.example.com`. Assume that the user logs in via `example.com`
- To enable sharing sessions across `example.com`, `abc.example.com` and `xyz.example.com`, set the `sessionTokenFrontendDomain` attribute to `.example.com`.
:::
## Steps
### 1. Update the frontend configuration
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.
```tsx
import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";
SuperTokens.init({
appInfo: {
// ...
// this should be equal to the domain where the user will see the login UI
apiDomain: "...",
appName: "...",
websiteDomain: "https://example.com",
},
recipeList: [
Session.init({
sessionTokenFrontendDomain: ".example.com",
}),
],
});
```
```tsx check=false reason="Partial configuration example"
supertokensUIInit({
appInfo: {
// ...
// this should be equal to the domain where the user will see the login UI
apiDomain: "...",
appName: "...",
websiteDomain: "https://example.com",
},
recipeList: [
supertokensUISession.init({
sessionTokenFrontendDomain: ".example.com",
}),
],
});
```
This change goes in the `supertokens-web-js` SDK configuration at the root of your application:
```tsx
import SuperTokens from "supertokens-web-js";
import Session from "supertokens-web-js/recipe/session";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
},
recipeList: [
Session.init({
sessionTokenFrontendDomain: ".example.com",
}),
],
});
```
:::warning
- Do not set `sessionTokenFrontendDomain` to a value that's in the [public suffix list](https://publicsuffix.org/list/public_suffix_list.dat) (Search for your value without the leading dot). Otherwise, session management does not work.
- Do not set `sessionTokenFrontendDomain` to `.localhost` or an IP address based domain with a leading `.` since browsers reject these cookies. For local development, you should configure [your machine to use alias for `localhost`](https://superuser.com/questions/152146/how-to-alias-a-hostname-on-mac-osx).
:::
:::info[Multi Tenancy]
If each tenant belongs to one subdomain, and a user has access to more than one tenant, the tenant ID in the session is always the one from which they logged in.
For example, if a user has access to tenant `t1.example.com` and `t2.example.com`, and they logged in via `t1.example.com`, then the tenant ID in the session is always `t1`. This remains true even if they navigate to `t2.example.com` or make an API request from `t2.example.com`.
To solve this, add extra information about access token payload containing a list of all the tenants that the user has access to. Then read from that list instead of the `tId` claim.
:::
:::warning[Not applicable]
:::
```tsx
import SuperTokens from "supertokens-web-js";
import Session from "supertokens-web-js/recipe/session";
SuperTokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
},
recipeList: [
Session.init({
sessionTokenFrontendDomain: ".example.com",
}),
],
});
```
```tsx check=false reason="Requires SDK globals from surrounding application"
supertokens.init({
appInfo: {
apiDomain: "...",
appName: "...",
},
recipeList: [
supertokensSession.init({
// ...
sessionTokenFrontendDomain: ".example.com",
}),
],
});
```
:::warning
- Do not set `sessionTokenFrontendDomain` to a value that's in the [public suffix list](https://publicsuffix.org/list/public_suffix_list.dat) (Search for your value without the leading dot). Otherwise, session management does not work.
- Do not set `sessionTokenFrontendDomain` to `.localhost` or an IP address based domain with a leading `.` since browsers reject these cookies. For local development, you should configure [your machine to use alias for `localhost`](https://superuser.com/questions/152146/how-to-alias-a-hostname-on-mac-osx).
:::
:::info[Multi Tenancy]
If each tenant belongs to one subdomain, and a user has access to more than one tenant, the tenant ID in the session is always the one from which they logged in.
For example, if a user has access to tenant `t1.example.com` and `t2.example.com`, and they logged in via `t1.example.com`, then the tenant ID in the session is always `t1`. This remains true even if they navigate to `t2.example.com` or make an API request from `t2.example.com`.
To solve this, add extra information about access token payload containing a list of all the tenants that the user has access to. Then read from that list instead of the `tId` claim.
:::
---
## See also