Skip to content

Customer accounts

This page walks through shopper accounts: sign-up and sign-in, the session, email links, password rules and pages that need a signed-in shopper. The kit’s useAuth hook and its auth routes do the work, and the routes call the SDK’s AuthApi. You need the proxy, the two route handlers and the provider from Install and configure.

The browser never sees a token. The access and refresh tokens live in httpOnly cookies named for the store, and the response bodies of the auth routes carry the shopper’s identity only. The hook calls your own /api/auth/<action> route, which calls the API.

useAuth gives the current shopper in user, a loading flag, isAnonymous and the sign-in methods. Each method returns { error }, where error is null on success and otherwise holds a message and the API’s code.

"use client";
import { errorCopyFor, useAuth } from "@ecomweb/storefront-kit";
export function LoginForm() {
const { signIn, user } = useAuth();
async function submit(email: string, password: string) {
const { error } = await signIn(email, password);
if (error) alert(errorCopyFor(error));
}
return user ? <p>Signed in as {user.email}</p> : <button onClick={() => submit("a@b.co", "secret")}>Sign in</button>;
}

The methods and the AuthApi call each one reaches:

useAuth method Does AuthApi call
signUp(email, password, name?) Registers an account. It does not sign the shopper in register
signIn(email, password) Signs in with a password login
sendLoginCode(email), verifyOtp(email, code) Signs in with a one-time code by email requestOtp, verifyOtp
signInWithGoogle(nextPath?) Sends the browser to Google, then back to nextPath getGoogleUrl, exchangeGoogleCode
signInAnonymously() Starts a guest identity that can hold a cart anonymous
signOut() Ends the session and clears the cookies logout

A store turns each sign-in method on or off. usePublicAuthConfig tells you which are on (password_enabled, google_enabled, otp_enabled) and whether the store requires email verification. A method that is off fails with AUTH_METHOD_DISABLED. Registering does not reveal whether an email already has an account: the API answers a new and an existing email the same way. If the shopper had a guest identity, the route upgrades that identity in place so its cart survives. It takes the identity from the session cookie and ignores anything the browser sends.

An access token expires quickly and a refresh token renews it. The kit refreshes in two places and you set neither up beyond the proxy file.

  • The middleware in proxy.ts checks the access token on every request it matches. When the token expires within 120 seconds, it calls AuthApi.refresh, waits at most 2.5 seconds and writes the new pair. If the refresh fails, the request goes on with the old token and nothing is cleared.
  • The backend proxy refreshes once when the API answers 401, then retries the call once. It never loops.

Server components read the session with getServerIdentity through requireSession and hasCustomerSession. Both share one lookup for each render. A signed-in session is different from an anonymous one. An anonymous identity holds a valid token but has no customer profile, and hasCustomerSession is false for it.

signOut ends only this session. Changing the password ends every session on the server and clears this browser’s cookies, so the shopper signs in again. The logout-all route does the same for all devices and needs a session.

Emails the API sends carry a token in a link. Your pages read the token from the link and post it to the kit’s auth route. useAuth has no method for these, so call the route with fetch. storeApiPath builds the right path in both modes.

import { storeApiPath } from "@ecomweb/storefront-kit";
const res = await fetch(storeApiPath(storeRef, "auth/verify-email"), {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ token }),
});
Route (POST) Body Does
auth/verify-email { token } Verifies the address from the registration email. See verifyEmail
auth/resend-verification { email } Sends the verification email again
auth/forgot-password { email } Sends a reset link
auth/reset-password { token, new_password } Sets a new password from the link
auth/change-password { current_password, new_password } Changes the password. Needs a session
auth/change-email { current_password, new_email } Sends a confirmation link to the new address. Needs a session
auth/change-email/confirm { token } Confirms the change. See confirmEmailChange

Each link is tied to the browser that asked for it. Registering and changing an email return a binding that the route keeps in an httpOnly cookie, and it sends the binding back with the token when the shopper opens the link. Open the link in the same browser. In another browser the address is verified but the password set at registration is dropped. Kits older than 0.13.1 do not do this and fail these steps against the current API. See Upgrade the storefront kit.

Each store sets its own password policy, and it comes with the public auth config as password_policy: min_length, require_number, require_symbol and require_uppercase. Do not hard-code a minimum. The API enforces the same rules and answers AUTH_WEAK_PASSWORD for a bad password. Checking in the browser only saves a round trip.

import { usePublicAuthConfig, validatePasswordAgainstPolicy } from "@ecomweb/storefront-kit";
const { config } = usePublicAuthConfig(storeRef);
const problem = config ? validatePasswordAgainstPolicy(password, config.password_policy) : null;

validatePasswordAgainstPolicy returns null when the password passes and a message otherwise. getPasswordPolicyHints lists the rules as short lines. Both return Vietnamese text today. To show your own wording, read the PasswordPolicy fields and write the message yourself.

In a server component, call requireSession at the top of every account page. It returns the customer and redirects when nobody, or only an anonymous guest, is signed in.

import { requireSession, resolveRootStoreRef } from "@ecomweb/storefront-kit/server";
export default async function OrdersPage() {
const storeRef = (await resolveRootStoreRef())!;
const customer = await requireSession(storeRef, "/login?next=/account/orders");
return <h1>Orders for {customer.email}</h1>;
}

When you send the shopper back after sign-in, pass the next value through safeRedirectPath. It resolves the value against the page’s origin and returns a same-origin path, or / for anything else, such as //evil.com, /\evil.com or javascript: URLs.

import { safeRedirectPath } from "@ecomweb/storefront-kit";
const target = safeRedirectPath(searchParams.get("next"), window.location.origin);
router.push(target);
Method What it does
useAuth The current shopper and the sign-up, sign-in and sign-out methods
usePublicAuthConfig Which sign-in methods are on and the password policy
createAuthRoutes The /api/auth route handlers behind the hook
requireSession Returns the signed-in customer or redirects
hasCustomerSession Whether the request has a real signed-in shopper
validatePasswordAgainstPolicy Checks a password against the store’s policy
safeRedirectPath Keeps a post-sign-in redirect on your own site
AuthApi.refresh Swaps a refresh token for a new token pair
AuthApi.me Reads the identity of an access token