LLM Docs Header: All requests to https://llm-docs.commercengine.io must include the Accept: text/markdown header (or append .md to the URL path). Without it, responses return HTML instead of parseable markdown.

Authentication & User Management

Prerequisite: SDK must be initialized. See setup/ if not done.

When to Implement Auth Directly

If using Hosted Checkout, login and registration are usually handled inside the checkout drawer. Build custom auth UI only when the storefront needs logged-in state outside checkout, for example:

account pages
saved addresses
order history
loyalty or wallet pages
a persistent signed-in header state

Current Mental Model

Public product and category reads can use public() and do not require anonymous auth.
Live cart, account, and checkout flows should use the session client.
In managed session mode, the SDK can bootstrap anonymous auth automatically on the first token-required request.
If you need the anonymous session eagerly, call sdk.ensureAccessToken() once during startup.

Quick Reference

Auth Method	Endpoint	Use Case
Anonymous bootstrap	`sdk.ensureAccessToken()` or `sdk.auth.getAnonymousToken()`	Start a live session
Email OTP	`sdk.auth.loginWithEmail()` -> `sdk.auth.verifyOtp()`	Passwordless email login
Phone OTP	`sdk.auth.loginWithPhone()` -> `sdk.auth.verifyOtp()`	Passwordless phone login
WhatsApp OTP	`sdk.auth.loginWithWhatsApp()` -> `sdk.auth.verifyOtp()`	Passwordless WhatsApp login
Password login	`sdk.auth.loginWithPassword()`	Traditional login
Password registration	`sdk.auth.registerWithPassword()` -> OTP verification	Password sign-up
Forgot password	`sdk.auth.forgotPassword()` -> `sdk.auth.resetPassword()`	Reset password with OTP
Token refresh	`sdk.auth.refreshToken()`	Renew expired access token

Decision Tree

User Request
    │
    ├─ Public catalog-only page
    │   └─ No auth bootstrap needed; use public()
    │
    ├─ New visitor starting a live session
    │   └─ sdk.ensureAccessToken()
    │
    ├─ "Login" / "Sign in"
    │   ├─ Passwordless → loginWithEmail/Phone/WhatsApp() → verifyOtp()
    │   └─ Password → loginWithPassword()
    │
    ├─ "Register"
    │   └─ registerWithPassword() / registerWithPhonePassword() → verifyOtp()
    │
    ├─ "Forgot password"
    │   └─ forgotPassword() → resetPassword()
    │
    ├─ "Account" / "Profile"
    │   └─ getUserDetails() / updateUserDetails()
    │
    └─ "Token expired" / 401
        └─ refreshToken() or rely on managed session refresh

User States

State	How Created	Capabilities
Public	`public()` accessor only	Public catalog/store/helper reads
Anonymous session	`sdk.ensureAccessToken()` or `/auth/anonymous`	Cart, checkout, analytics, session continuity
Logged-in session	OTP verification, password login, or password reset completion	All anonymous capabilities plus account, orders, addresses, loyalty

User ID vs Customer ID

For most stores, user_id and customer_id are the same value — one user = one customer. In B2B storefronts, one customer can have multiple users (e.g., a company account with multiple employees).

The SDK exposes helpers to fetch both:

const userId = await sdk.getUserId();
const customerId = await sdk.getCustomerId();

Most SDK methods that require a user or customer ID have parameterless overloads that auto-resolve from the current session. For example, sdk.cart.getUserCart() (no params) fetches the cart for the logged-in user automatically. Only pass IDs explicitly when operating on behalf of a different user (admin scenarios).

Key Patterns

Start a live anonymous session

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

Call this once during startup if you want eager bootstrap. Do not repeat it before ordinary session-aware cart, order, or customer calls.

OTP Login Flow (Email)

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

if (error) throw error;

const { otp_token, otp_action } = data!;

const { error: verifyError } = await sdk.auth.verifyOtp({
  otp: "123456",
  otp_token,
  otp_action,
});

if (verifyError) throw verifyError;

Password Login

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

if (error) throw error;

Password Registration

Password registration is OTP-first in the latest contract.

const { data, error } = await sdk.auth.registerWithPassword({
  email: "user@example.com",
  password: "securepassword",
  confirm_password: "securepassword",
});

if (error) throw error;

await sdk.auth.verifyOtp({
  otp: "123456",
  otp_token: data!.otp_token,
  otp_action: data!.otp_action,
});

Forgot Password

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

if (error) throw error;

await sdk.auth.resetPassword({
  otp: "123456",
  otp_token: data!.otp_token,
  new_password: "newPass123",
  confirm_password: "newPass123",
});

User Profile

Auth client methods require explicit IDs (no parameterless overloads). Use sdk.getUserId() to get the current user's ID:

const userId = await sdk.getUserId();

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

await sdk.auth.updateUserDetails({ id: userId! }, {
  first_name: "Jane",
  last_name: "Doe",
});

Key Feature: `register_if_not_exists`

Setting register_if_not_exists: true on login endpoints eliminates separate login and sign-up entry points. If the user does not exist, Commerce Engine creates the account and continues the OTP flow.

This is also the recommended approach for checkout auth — there is no separate "guest checkout" flow. The user provides their email or phone, gets verified via OTP, and the account is created if needed. This path of least resistance ensures address verification and order attribution. Hosted Checkout handles this entire flow automatically.

Logout

Logout is handled by Hosted Checkout when using managed auth mode — the checkout UI includes login/logout. The SDK also exposes sdk.auth.logout() for custom logout buttons:

const { data, error } = await sdk.auth.logout();

logout() does not clear tokens — it returns new tokens with reduced privileges. The session continues with full continuity (same cart, same analytics trail), but the user is no longer in a logged-in state. The SDK's onTokensUpdated callback fires with the new tokens, so Hosted Checkout (if using authMode: "provided") automatically receives them.

Common Pitfalls

Level	Issue	Solution
CRITICAL	Using `public()` for auth or account operations	Use the session client
CRITICAL	Assuming every page needs anonymous auth	Public reads do not; only live session flows do
HIGH	Building separate login and sign-up flows by default	Prefer `register_if_not_exists: true` where appropriate
HIGH	Forgetting `otp_token` and `otp_action` between steps	Persist both and pass them to `verifyOtp()`
HIGH	Storing tokens insecurely or with the wrong storage for the runtime	Use managed session storage appropriate to the environment
MEDIUM	Ignoring `{ data, error }`	Always check `error` before using `data`

Documentation

Authentication Guide: https://www.commercengine.io/docs/storefront/authentication
My Account: https://www.commercengine.io/docs/storefront/my-account
LLM Reference: https://llm-docs.commercengine.io/storefront/operations/get-anonymous-token

ce-auth

Authentication & User Management

When to Implement Auth Directly

Current Mental Model

Quick Reference

Decision Tree

User States

User ID vs Customer ID

Key Patterns

Start a live anonymous session

OTP Login Flow (Email)

Password Login

Password Registration

Forgot Password

User Profile

Key Feature: `register_if_not_exists`

Logout

Common Pitfalls

See Also

Documentation

ce-auth

Authentication & User Management

When to Implement Auth Directly

Current Mental Model

Quick Reference

Decision Tree

User States

User ID vs Customer ID

Key Patterns

Start a live anonymous session

OTP Login Flow (Email)

Password Login

Password Registration

Forgot Password

User Profile

Key Feature: register_if_not_exists

Logout

Common Pitfalls

See Also

Documentation

Key Feature: `register_if_not_exists`