Skip to main content

​
Overview

The User Session is automatically saved in two cookies:

stytch_session

Contains the opaque session_token returned from the API.

stytch_session_jwt

Contains the session_jwt returned from the API.
For example, if the SDK is loaded on https://app.example.com, the cookies will be set as:
  • document.cookie = "stytch_session=secret-session; domain=app.example.com; path=/; SameSite=Lax; Secure; max-age=whenever-it-expires"
  • document.cookie = "stytch_session_jwt=eyJhxxx.xxx.xxx; domain=app.example.com; path=/; SameSite=Lax; Secure; max-age=whenever-it-expires"
The cookie will not be marked as secure if the SDK is loaded on localhost.
The Stytch SDK allows you to configure the following directives and values for cookie management via cookieOptions: 
{
  "cookieOptions": {
    /**
     * The name of the cookie containing the opaque Stytch session token.
     * Defaults to `stytch_session`.
     */
    "opaqueTokenCookieName": "string",

    /**
     * The name of the cookie containing the opaque Stytch session token.
     * Defaults to `stytch_session_jwt`.
     */
    "jwtCookieName": "string",

    /**
     * What HTTP paths the cookies should be available on.
     * Equal to configuring the `;path=${}` param in the set-cookie directive.
     * Defaults to unset.
     */
    "path": "string",

    /**
     * What domain the cookies should be available on.
     * Equal to configuring the `;domain=${}` param in the set-cookie directive.
     * Requires setting availableToSubdomains to have any effect.
     * Defaults to unset.
     */
    "domain": "string",

    /**
     * Whether to make the cookies available to subdomains.
     * When true, equivalent to configuring the `;domain=${window.location.host}` directive.
     * When false, equivalent to leaving the directive unset.
     * Defaults to false.
     */
    "availableToSubdomains": "boolean"
  }
}
1

Set cookie options in the SDK client

To override default values, set the desired values in the cookieOptions configuration and pass it as part of the optional second parameter when initializing the Stytch SDK client:
import { StytchUIClient } from "@stytch/vanilla-js"

const STYTCH_PUBLIC_TOKEN = 'YOUR_PUBLIC_TOKEN';

const stytchOptions = {
  cookieOptions: {
    opaqueTokenCookieName: "my_stytch_session",
    jwtCookieName: "my_stytch_session_jwt",
    path: "/",
    availableToSubdomains: true,
    domain: "app.example.com",
  }
}

const stytchClient = new StytchUIClient(STYTCH_PUBLIC_TOKEN, stytchOptions)
cookieOptions do not apply to HttpOnly cookies.

​
HttpOnly cookies

For added security, you can enable the use of HttpOnly cookies for your project. This moves cookie management from the client to Stytch’s backend. When HttpOnly cookies are used, Stytch’s backend sets the Domain of the cookie to the parent of your custom domain. Cookies are accessible to the Domain specified and all its subdomains, for example:
  • If your custom domain is login.example.com, the Domain will be set to example.com, making the cookies accessible to example.com, app.example.com, login.example.com, etc.
  • If your custom domain is login.app.example.com, the Domain will be set to app.example.com, making the cookies accessible to app.example.com and its subdomains, but not example.com.
By default, cookies managed by the SDK running in the client are not marked as HttpOnly.

​
Enable HttpOnly cookies

Important things to consider before enabling HttpOnly cookies:

​
Requirements

  1. Using HttpOnly cookies requires a custom domain to be set up for your Stytch project to allow Stytch’s backend to set cookies in a first-party context for your domain.
  2. HttpOnly cookies are only supported in the live environment.

​
Considerations

  1. Using HttpOnly cookies means the cookies are no longer accessible via JavaScript in the browser. This includes the session_token and session_jwt. These tokens are omitted from any response bodies to the client.
  2. session.getTokens() will no longer return session tokens when an active session exists.
  3. session.updateSession() will only work if there’s not an existing session token set using an HttpOnly cookie. Make sure cookieOptions are configured to match the domain and cookie names used by Stytch’s backend if you use this method.
  4. If the HttpOnly cookies setting is set to enforced, Stytch will only accept browser requests for your project that use your custom domain.
  5. cookieOptions does not apply to HttpOnly cookies.
1

Set a custom domain

Configure a custom domain for your project.
2

Enable HttpOnly cookies

Set the HttpOnly cookies setting to Enabled under the Frontend SDK settings.
3

Update your SDK client

In your application, set the customBaseUrl option in your Stytch SDK client to your custom domain to tell the SDK to use your custom domain for requests.
We recommend initially changing this setting in a staging environment before enabling it in production.
4

Test your implementation

Verify that your application behaves as expected. The stytch_session and stytch_session_jwt cookies should now be marked as HttpOnly.
5

Enforce HttpOnly cookies

After confirming your implementation works as expected, you can set the HttpOnly cookies setting to Enforced to require all browser requests to use your custom domain.
This will block all browser SDK requests that do not use your custom domain.

​
Disable HttpOnly cookies

1

Remove the customBaseUrl setting

Stop using HttpOnly cookies by removing the customBaseUrl setting from your Stytch client configuration.
This will not remove existing HttpOnly cookies from the user’s browser, which the SDK will be unable to access.To avoid disruptions to existing sessions, have your backend replace HttpOnly cookies with non-HttpOnly cookies.