> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Sessions

> How Catalyst manages customer sessions and access tokens using Auth.js.

[Auth.js](https://authjs.dev/) manages session persistence by issuing a session cookie that embeds a JWT along with session data. In Catalyst, this session data includes the [customer access token](/developer/docs/storefront/guides/graphql-storefront-api/authentication), which allows your app to authenticate shoppers without storing session data on the server.

In any request, the session cookie authenticates the customer with the Catalyst app, while a customer access token authenticates them with BigCommerce so that you can add customer-specific context to many GraphQL operations. BigCommerce uses the customer access token to associate the request with the authenticated shopper and return personalized customer data.

Here's how the flow works in Catalyst:

1. **Anonymous session:** The [`withAuth` proxy](/developer/docs/storefront/catalyst/development/middleware#with-auth) creates an anonymous Auth.js session, stored in the `authjs.anonymous-session-token` cookie, the first time a shopper visits the storefront. When the shopper signs in, Catalyst issues an authenticated session that carries a customer access token, and clears the anonymous session.
2. **Customer access token issuance:** BigCommerce issues a customer access token when the shopper signs in, with a password or a JWT.
3. **Storage in the Auth.js session:** Auth.js stores the customer access token in the session. The `callbacks.jwt` function embeds the token in the JWT when the shopper signs in, and the `callbacks.session` function exposes it on the session object.
4. **Session retrieval:** When your app needs session data, it calls the `auth()` function, which returns the session object with the customer access token.
5. **Requests on behalf of the customer:** To call BigCommerce as the customer, get the token from the session with Catalyst's `getSessionCustomerAccessToken` utility and pass it to the request. Requests that return customer-specific data must skip the Data Cache, so guest shoppers never receive another customer's data. See [Caching](/developer/docs/storefront/catalyst/development/caching#anonymous-vs-customer-specific-requests).

This request passes the customer access token and skips the cache when the shopper is signed in:

```ts showLineNumbers={false}
import { getSessionCustomerAccessToken } from '~/auth';
import { revalidate } from '~/client/revalidate-target';

const customerAccessToken = await getSessionCustomerAccessToken();

const response = await client.fetch({
  document: ProductQuery,
  customerAccessToken,
  fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
});
```

## Built-in functionality supported by the customer context

The customer context that comes from the customer access token supports the following built-in functionality. Each item is tied to the signed-in customer's session.

* **Order history:** Retrieve the customer's order history, including order status, total amount, shipping details, and line items.
* **Personalized cart data:** Access the customer's cart, including line items, quantities, pricing, and selected options.
* **Customer group-based pricing:** Apply customer group-specific pricing rules to products and cart items.
* **Customer group-based catalog visibility:** Restrict or allow access to specific products or categories based on the customer's group.
* **Account information:** Retrieve customer account details such as name, email, and company information.
* **Address management:** Access and manage customer shipping and billing addresses.
* **Checkout redirection:** Generate a personalized checkout URL for the customer.
* **Tax and currency settings:** Apply tax and currency settings based on the customer's location and account.
* **Personalized promotions:** Apply promotions and discounts specific to the customer or their group.
* **Wishlist and saved items:** Access and manage the customer's wishlist or saved items.
* **Customer-specific product recommendations:** Provide personalized product recommendations based on the customer's purchase history or preferences.
* **Customer-specific shipping options:** Display shipping options tailored to the customer's address and preferences.
* **Customer-specific tax exemptions:** Apply tax exemptions for eligible customers (for example, wholesale customers or tax-exempt organizations).