Switch between cookie and header-based sessions

caution

We recommend cookie-based sessions in browsers because header-based sessions require saving the access and refresh tokens in storage vulnerable to XSS attacks.

Supertokens supports 2 methods of authorizing requests:

• Based on cookies
  • The default in our web SDKs
  • Uses HttpOnly cookies by default to prevent token theft via XSS
• Based on the Authorization header
  • The default in our mobile SDKs
  • Uses the Authorization header with a Bearer auth-scheme
  • This can make it easier to work with API gateways and third-party services
  • Preferable in mobile environments, since they can have buggy and/or unreliable cookie implementations

When creating/authorising sessions, the SDK has to choose to send the tokens to the frontend by cookies or custom headers. This choice is ultimately controlled by the backend, but it follows a preference set in the frontend configuration.

Frontend configuration

You can provide a tokenTransferMethod property in the configuration of the Session recipe to set the preferred token transfer method, which will be sent to the backend with every request in the st-auth-mode header.

By default, the backend follows this preference.

What type of UI are you using?

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

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            tokenTransferMethod: "header" // or "cookie"
        })
    ]
});

Backend configuration (Optional)

important

By returning a fixed value from getTokenTransferMethod you can strictly control the allowed session types regardless of the frontend config.

You should not set this on the backend if you have more than one client using different modes (for example if you have a website that uses cookie based, and a mobile app that uses header based sessions).

You can provide a getTokenTransferMethod callback in the configuration of the Session recipe.

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

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            getTokenTransferMethod: () => "header",
        })
    ]
});

note

By default, we allow both cookie and authorization bearer tokens during session verification. When creating a new session, we follow the preference of the frontend indicated by the st-auth-mode request header (set by the frontend SDK).