Which UI do you use?

Custom UI

Pre built UI

Working with multiple API endpoints

To enable use of sessions for multiple API endpoints, you need to use the sessionTokenBackendDomain config on the frontend and cookieDomain on the backend Session.init function call.

important

• All your API endpoints must have the same top level domain. For example, they can be {"api.example.com", "api2.example.com"}, but they cannot be {"api.example.com", "api.otherdomain.com"}.
• sessionTokenBackendDomain in the frontend config must match the cookieDomain set in the backend config.

Step 1) Backend config

You need to set the sessionTokenBackendDomain value to be the common top level domain. For example, if your API endpoints are {"api.example.com", "api2.example.com", "api3.example.com"}, the common portion of these endpoints is ".example.com" (The dot is important). So you would need to set the following:

NodeJS

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

GoLang

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            cookieDomain: ".example.com",
        })
    ]
});

Python

import (
    "github.com/supertokens/supertokens-golang/recipe/session"
    "github.com/supertokens/supertokens-golang/recipe/session/sessmodels"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    cookieDomain := ".example.com"

    supertokens.Init(supertokens.TypeInput{
        RecipeList: []supertokens.Recipe{
            session.Init(&sessmodels.TypeInput{
                CookieDomain: &cookieDomain,
            }),
        },
    })
}

Other Frameworks

from supertokens_python import init, InputAppInfo
from supertokens_python.recipe import session


init(
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    framework='...', 
    recipe_list=[
        session.init(
            cookie_domain='.example.com'
        )
    ]
)

The above will set the session cookies' domain to .example.com, allowing them to be sent to *.example.com.

note

Whilst the cookieDomain can start with a leading ., the value of the apiDomain in appInfo must point to an exact API domain only. This should be the API in which you want to expose all the auth related endpoints (for example /auth/signin).

For local development, you should not set the cookieDomain to an IP address based domain, or .localhost - browsers will reject these cookies. Instead, you should alias localhost to a named domain and use that.

Step 2) Frontend config

You need to set the same value for sessionTokenBackendDomain on the frontend. This will allow the frontend SDK to apply interception and automatic refreshing across all your API calls:

ReactJS

Important

SuperTokens does not provide non-React UI components. So we will be using the supertokens-auth-react SDK and will inject the React components to show the UI. Therefore, the code snippet below refers to the supertokens-auth-react SDK.

import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            sessionTokenBackendDomain: ".example.com" 
        })
    ]
});

Angular

Important

SuperTokens does not provide non-React UI components. So we will be using the supertokens-auth-react SDK and will inject the React components to show the UI. Therefore, the code snippet below refers to the supertokens-auth-react SDK.

import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            sessionTokenBackendDomain: ".example.com" 
        })
    ]
});

Vue

import SuperTokens from "supertokens-auth-react";
import Session from "supertokens-auth-react/recipe/session";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            sessionTokenBackendDomain: ".example.com" 
        })
    ]
});