> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookies & sessions

> Options for cookie configuration options and HttpOnly cookies.

## Overview

The User Session is automatically saved in two cookies:

<Columns cols={2}>
  <Card title="stytch_session">
    Contains the opaque `session_token` returned from the API.
  </Card>

  <Card title="stytch_session_jwt">
    Contains the `session_jwt` returned from the API.
  </Card>
</Columns>

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"`

<Note>
  The cookie will not be marked as secure if the SDK is loaded on `localhost`.
</Note>

***

## Configure cookie options

The Stytch SDK allows you to configure the following directives and values for cookie management via `cookieOptions`:

```json expandable theme={null}
{
  "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"
  }
}
```

<Steps>
  <Step title="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:

    ```javascript lines theme={null}
    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)
    ```
  </Step>
</Steps>

<Note>
  `cookieOptions` do not apply to HttpOnly cookies.
</Note>

***

## 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`.

<Note>
  By default, cookies managed by the SDK running in the client are not marked as `HttpOnly`.
</Note>

***

### 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 not supported in localhost environments.

#### 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.

***

<Steps>
  <Step title="Set a custom domain">
    Configure a [custom domain](https://stytch.com/dashboard/custom-domains) for your project.
  </Step>

  <Step title="Enable HttpOnly cookies">
    Set the HttpOnly cookies setting to `Enabled` under the [Frontend SDK settings](https://stytch.com/dashboard/sdk-configuration?env=live).
  </Step>

  <Step title="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.

    <Tip>
      We recommend initially changing this setting in a staging environment before enabling it in production.
    </Tip>
  </Step>

  <Step title="Test your implementation">
    Verify that your application behaves as expected. The `stytch_session` and `stytch_session_jwt` cookies should now be marked as `HttpOnly`.
  </Step>

  <Step title="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.

    <Warning>
      This will block all browser SDK requests that do not use your custom domain.
    </Warning>
  </Step>
</Steps>

***

### Disable HttpOnly cookies

<Steps>
  <Step title="Remove the customBaseUrl setting">
    Stop using HttpOnly cookies by removing the `customBaseUrl` setting from your Stytch client configuration.
  </Step>
</Steps>

<Warning>
  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.
</Warning>