October, 2026 release

Setting up storefront authentication and session management

Essential runtime integration steps for B2C/B2B storefront developers. Details resolveContext flow routing, cookie lifecycle behavior, and Phase 1 (JWT) to Phase 2 (cookie) authentication handoffs.

Authenticating the storefront (B2C / B2B)

Storefront authentication uses the Identity 's resolveContext mutation as the single entry point. On every request, the Context Proxy or Shell invokes resolveContext using three possible inputs:

channelId
Always present. Storefront channel identifier (NanoID format).
cookieValue
Present after first request. Signed commerce_user_token cookie value.
jwt
Present after user login. Auth0 JWT for registered user authentication.

Routing Decision Matrix

cookieValue jwt Action Description
Absent Absent GUEST_CREATED Creates a new guest user and corresponding session.
Present Absent SESSION_VALIDATED / SESSION_INVALID Validates an existing session cookie.
Present Present CONVERTED Converts a guest user to a registered user and merges carts.
Absent Present DIRECT_LOGIN_REGISTERED Executes direct registered user login without a prior guest session.

Session Token Structure (commerce_user_token)

The session token is a signed, httpOnly cookie with the following security attributes:

  • Format: <session_token>.<HMAC_signature>
  • Signing Algorithm: HMAC-SHA256 using SESSION_SIGNING_SECRET (minimum 32 characters).
  • Storage Tables: Server-side session_liveness and session_context database tables.
  • Security Directives: Configured with httpOnly, Secure, and SameSite=Lax to prevent client-side script access.

ResolveContext Response GraphQL Payload

type ResolveContextPayload {
  action: String!           # GUEST_CREATED | SESSION_VALIDATED | CONVERTED | ...
  accountId: String         # Tenant account ID
  userId: String            # User NanoID
  userType: String          # guest | b2c | b2b | admin
  activeOrgId: String       # Primary organization
  eligibleOrgIds: [String!] # All org memberships
  personaIds: [String!]     # Assigned personas
  workspaceIds: [String!]   # Contract-derived workspace IDs
  activeContractId: String  # Primary contract
  eligibleContractIds: [String!]
  segmentIds: [String!]     # Customer segment memberships
  activeLocale: String      # e.g., "en-CA"
  activeCurrency: String    # e.g., "CAD"
  sessionType: String       # guest | registered
  setCookie: String         # Set-Cookie header directive
  clearCookie: String       # Clear-Cookie header directive for invalid sessions
  xContext: String          # Base64-encoded X-Context header string
  isPreview: Boolean        # Preview override indicator
}

Managing token lifecycle and propagation

Authentication transition occurs across two main execution phases:

Phase 1: Initial Auth (JWT bearer)
The browser authenticates with Auth0 to receive an id_token. The shell passes Authorization: Bearer <id_token> to the gateway, which forwards it to Identity via resolveContext. The Identity sets the commerce_user_token cookie in the response.
Phase 2: Subsequent Requests (httpOnly cookie)
The browser transmits requests containing the commerce_user_token cookie without Bearer headers. The Gateway injects the Base64-encoded x-context header along with context identifiers (x-account-id, x-user-id, x-org-id) to downstream subgraphs.

Token Storage Matrix

Token Storage Location Accessible to JavaScript?
Auth0 id_token In-memory (_cachedToken) with localStorage fallback Yes (Temporary)
Auth0 access_token Encrypted secure storage No (Via secureStorage API only)
Auth0 refresh_token Encrypted secure storage No (Via secureStorage API only)
commerce_user_token httpOnly cookie No (Sent automatically by browser)