Authentication - Commerce Engine Docs

Commerce Engine distinguishes public requests from live user sessions.

State	How it is used	Typical capabilities
Public	Public SDK accessor or operation’s publishable-key auth	Product browsing, categories, search, recommendations, store configuration
Anonymous session	Session SDK creates or restores an anonymous token pair	Cart, live session continuity, checkout preparation, session analytics
Logged-in session	OTP or password verification upgrades the session	Account, addresses, loyalty, orders, authenticated checkout

Public browsing does not require anonymous authentication. Establish a live session only when the application needs session-bound behaviour or when it intentionally bootstraps one at startup.

Recommended implementation paths

Hosted Checkout

Recommended when login is primarily needed for checkout. Hosted Checkout handles OTP, account switching, addresses, payment, and order confirmation.

Custom auth UI

Build this when the storefront needs login state outside checkout—for example, account, orders, loyalty, wishlist, or saved addresses.

Session bootstrap

For a browser SPA:

const sdk = storefront.session();
await sdk.ensureAccessToken();

For Next.js, TanStack Start, Astro, and SvelteKit, mount storefront.bootstrap() once in a root client boundary. Returning users reuse existing cookie-backed sessions. Do not create anonymous sessions during SSG, ISR, prerendering, or public server rendering. Use the public accessor in those contexts.

Anonymous session bootstrap

Commerce Engine supports email, phone, and WhatsApp OTP flows. Set register_if_not_exists: true to provide one login/register entry point.

1. Request an OTP

const { data: challenge, error } = await sdk.auth.loginWithEmail({
  email: "customer@example.com",
  register_if_not_exists: true,
});

if (error || !challenge) {
  throw new Error(error?.message ?? "OTP could not be sent");
}

Phone and WhatsApp flows include the country code:

const { data: challenge, error } = await sdk.auth.loginWithPhone({
  phone: "9876543210",
  country_code: "+91",
  register_if_not_exists: true,
});

if (error || !challenge) {
  throw new Error(error?.message ?? "OTP could not be sent");
}

Persist both otp_token and otp_action in temporary form state. They belong to this verification attempt.

2. Verify the OTP

const { data: verified, error } = await sdk.auth.verifyOtp({
  otp: userEnteredOtp,
  otp_token: challenge.otp_token,
  otp_action: challenge.otp_action,
});

if (error) throw new Error(error.message);

The SDK stores the new logged-in token pair when managed token storage is configured.

Passwordless login and registration

UX requirements

A production OTP flow should include:

[ ] clear contact destination
[ ] resend with rate-limit/countdown state
[ ] expired and incorrect OTP messages
[ ] loading and duplicate-submit protection
[ ] editable email/phone before verification
[ ] post-login query invalidation
[ ] accessible segmented or single OTP input

Resend by requesting a new challenge and replacing the old otp_token and otp_action.

Anonymous cart continuity

When an anonymous user logs in, Commerce Engine merges the active anonymous cart into the account session. Do not:

create a new cart after login
copy cart items client-side
discard the returned token pair

Refresh or invalidate the cart query after successful verification so the UI displays the merged state.

Password authentication

Password login is available for stores that enable it:

const { data, error } = await sdk.auth.loginWithPassword({
  email: "customer@example.com",
  password,
});

if (error) throw new Error(error.message);

Password registration and reset can require OTP verification. Retrieve the exact operation contract from the LLM-first reference before building those flows rather than assuming one common request shape.

Reading authentication state

Use token helpers for fast UI state without an extra API call:

const userInfo = await sdk.getUserInfo();
const isLoggedIn = await sdk.isLoggedIn();
const isAnonymous = await sdk.isAnonymous();
const userId = await sdk.getUserId();
const customerId = await sdk.getCustomerId();

Use these values for presentation and route decisions. Server-side authorization must still rely on the request-bound session and the API operation result.

Automatic refresh and session recovery

With managed storage, the SDK refreshes expired access tokens, persists rotated tokens, and retries the original operation once. Concurrent requests should share one refresh rather than launching several refresh calls.

Automatic token refresh

After a long absence, recovery should restore a usable anonymous session without blocking public browsing. Protected routes can then ask the customer to authenticate again.

Session recovery after a long absence

User versus customer ID

For many B2C stores, user and customer IDs align. B2B accounts can contain multiple users under one customer. Prefer SDK overloads that resolve identity from the active session:

const { data: addresses } = await sdk.customer.listAddresses();
const { data: orders } = await sdk.order.listOrders();
const { data: cart } = await sdk.cart.getUserCart();

Auth profile methods may require an explicit user ID:

const userId = await sdk.getUserId();
if (!userId) throw new Error("No active user");

const { data, error } = await sdk.auth.getUserDetails({ id: userId });

Do not accept an arbitrary browser-supplied user ID for a protected server operation when the SDK can infer the authenticated identity.

Profile updates

const userId = await sdk.getUserId();
if (!userId) throw new Error("Login required");

const { data, error } = await sdk.auth.updateUserDetails(
  { id: userId },
  { first_name: "Asha", last_name: "Sharma" },
);

if (error) throw new Error(error.message);

Changing a verified email or phone may require a dedicated OTP action. Confirm the exact operation and verification sequence from the current LLM reference.

Logout

Logout downgrades the logged-in session to a new anonymous session linked to the continuing journey.

const { data, error } = await sdk.auth.logout();
if (error) throw new Error(error.message);

With managed session storage, the SDK stores the returned anonymous tokens. Do not call clearTokens() after a successful logout. After logout:

remove protected account data from local caches
invalidate cart/session queries
update header UI from the new anonymous user state
redirect away from protected routes

The anonymous cart and session identity can continue.

Logout with anonymous continuity

Hosted Checkout authentication

Checkout-only integration

When Hosted Checkout is the only Commerce Engine integration, use its default managed mode. Checkout owns anonymous bootstrap, OTP login, refresh, and logout.

Storefront SDK plus Hosted Checkout

When the app also uses @commercengine/storefront, the Storefront SDK is the session owner. Use authMode: "provided" and two-way token synchronization. This requirement applies even when the app has no custom auth form. Otherwise the SDK and checkout create separate users/carts. See Hosted Checkout configuration.

Route protection

Protect account routes using the framework’s request-bound session accessor where possible. A useful guard distinguishes:

no session / anonymous → redirect to login
logged-in session → render
upstream failure → error/retry state, not automatic login redirect

Do not treat every API error as proof the user is logged out.

Token storage and security

Use the storage model designed for the runtime:

browser SPA: BrowserTokenStorage
first-party SSR wrapper: built-in aligned cookie storage
custom SSR/BFF: request-bound ServerTokenStorage or server-side session storage
Node.js: request- or user-isolated storage

The Storefront API key is publishable. Private admin keys, payment credentials, and webhook secrets remain server-only. Never log access tokens, refresh tokens, OTPs, passwords, or full authentication responses.

Direct REST integration

Direct API clients must manage:

/auth/anonymous session creation
Bearer tokens
refresh and retry
response content envelopes
token replacement after login, refresh, and logout

Use the generated API reference for exact headers and operation contracts. SDK examples access unwrapped data and must not be copied into a direct REST client unchanged.

Production checklist

[ ] public pages do not create sessions unnecessarily
[ ] one root session bootstrap for live flows
[ ] OTP challenge state includes token and action
[ ] resend replaces the previous challenge
[ ] login preserves/merges the anonymous cart
[ ] logout stores returned anonymous tokens
[ ] protected caches cleared after logout
[ ] route guards distinguish anonymous state from upstream failure
[ ] Storefront SDK and Hosted Checkout share one session
[ ] tokens, OTPs, and passwords are never logged
[ ] auth journeys tested in the production build

Exact auth operations

Retrieve current auth method signatures and types with a .md URL or Accept: text/markdown before implementation.

​Recommended implementation paths

Hosted Checkout

Custom auth UI

​Session bootstrap

​Passwordless OTP login

​1. Request an OTP

​2. Verify the OTP

​UX requirements

​Anonymous cart continuity

​Password authentication

​Reading authentication state

​Automatic refresh and session recovery

​User versus customer ID

​Profile updates

​Logout

​Hosted Checkout authentication

​Checkout-only integration

​Storefront SDK plus Hosted Checkout

​Route protection

​Token storage and security

​Direct REST integration

​Production checklist