> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Authentication verifies the identity of the user interacting with your storefront. Commerce Engine uses a robust token-based system (JWT) and offers flexible login methods, including passwordless options via Email, Phone, and WhatsApp.
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
Recommended when login is primarily needed for checkout. Hosted Checkout handles OTP, account switching, addresses, payment, and order confirmation.
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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
## Passwordless OTP login
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
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
### UX requirements
A production OTP flow should include:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] 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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
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.
## 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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
## 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](/docs/hosted-checkout/configuration#recommended-token-sync-pattern-storefront-sdk--hosted-checkout).
## 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] 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
```
Retrieve current auth method signatures and types with a `.md` URL or `Accept: text/markdown` before implementation.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.