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.
Sign up and sign in
Section titled “Sign up and sign in”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.
Sessions and refresh
Section titled “Sessions and refresh”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.tschecks the access token on every request it matches. When the token expires within 120 seconds, it callsAuthApi.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.
Email verification and change
Section titled “Email verification and change”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.
Password rules
Section titled “Password rules”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.
Protect account pages
Section titled “Protect account pages”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);Key methods
Section titled “Key methods”| 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 |