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

# Customer Session Management

Plan: Composable Developer

Lesson 16 of 19 · 15 min

As we've seen, Catalyst uses a customer access token obtained during customer login to identify that customer's context when making GraphQL Storefront API queries and mutations.

This is one part of the full picture of managing a customer's session, which we'll look at in more detail now.

## Auth.js

[Auth.js](https://authjs.dev/) is an open-source solution for managing the common tasks of customer authentication.

BigCommerce is, naturally, the customer authentication provider for Catalyst by default, but Auth.js wraps the simple authentication piece into a reliable system for tracking and managing the customer session.

With the default Catalyst configuration, Auth.js tracks a logged-in customer's session using a JWT cookie. Important files related to the Auth.js integration include:

* **auth/index.ts**: This file contains the central configuration and exports key components for other code to interact with. The simple BigCommerce authentication provider is defined here, and the `getSessionCustomerAccessToken` method exported here can be used to easily retrieved the logged-in customer's token. The storefront's login and logout operations utilize functions exported from this file as well.
* **app/api/auth/\[...nextauth]/route.ts**: Exports the API endpoints needed by Auth.js.
* **proxies/with-auth.ts**: Invokes Auth.js in all requests to ensure customer session is kept alive.

## Session Sync

The GraphQL Storefront API supports syncing a customer's authenticated session between different front-end applications.

In the default Catalyst experience, this is primarily relevant to the Redirected Checkout process, as customers who have logged in on the Catalyst storefront need to *remain* logged in when they arrive at BigCommerce checkout.

The `createCartRedirectUrls` GraphQL mutation used to redirect visitors takes the current customer access token into account, and the tokenized redirect URL handles syncing both cart and authenticated status when the visitor arrives at checkout.

See `app/[locale]/(default)/checkout/route.ts` for the details of the redirect process.

## Single Sign-on

The URL path `/login/token/{token}` can be used in Catalyst to log in a customer using a specialized token instead of user-provided credentials. This supports single sign-on scenarios, when a customer's identity has already been authenticated by an outside application.

This process requires a JSON Web Token (JWT) signed by a registered BigCommerce app and containing a payload identifying the customer to be logged in. See [Customer Login API](/developer/docs/storefront/guides/customer-authentication/customer-login) in the BigCommerce developer docs for the details of generating a valid JWT.

See these related files for more details on the Catalyst implementation:

* **auth/index.ts** - The `loginWithCustomerLoginJwt` GraphQL mutation used here is responsible for the authentication process.
* **app/\[locale]/(default)/(auth)/login/token/\[token]/route.ts** - This route handles the request to `/login/token/{token}`.

## Resources

* [Auth.js](https://authjs.dev/)
* [Customer Login API](/developer/docs/storefront/guides/customer-authentication/customer-login)
* [Customer Sessions](/developer/docs/storefront/catalyst/development/sessions)