Authentication

Register

const {data, error} = await client.auth.register({
  email: '[email protected]',
  password: 'securePassword123',
  firstName: 'Jan',
  lastName: 'Novak',
});
if (error) return showError(error);
if (data.pendingApproval || data.pendingEmailVerification) {
  return showPending({approval: data.pendingApproval, emailVerification: data.pendingEmailVerification});
}
// Tokens are set only when neither policy gate is pending.

Pass the company details with the registration. EU VAT IDs are verified in VIES on the server: a confirmed one creates the customer's default billing address (vatIdValid: true) and, when the merchant enabled it on a customer group, joins the customer to that group (for example "EU companies" with its own price list or price rule). An invalid VAT ID never blocks the sign-up.

await client.auth.register({
  email: '[email protected]',
  password: '...',
  firstName: 'Jana',
  lastName: 'Nováková',
  company: 'Nováková s.r.o.',
  companyId: '12345678',
  vatId: 'SK2020000000',
  country: 'SK',
});

const {data: tokens, error} = await client.auth.login({
  email: '[email protected]',
  password: 'securePassword123',
});

Token Refresh

The SDK automatically refreshes tokens after a 401 when that client holds a refresh token. Its lock covers requests on that one client instance. You can also refresh manually:

const {data: newTokens, error} = await client.auth.refresh();

Logout

await client.auth.logout();
// Tokens cleared, refresh token invalidated server-side

Password Reset

// Request reset email
await client.auth.forgotPassword('[email protected]');

// Reset with token from email
await client.auth.resetPassword(token, 'newSecurePassword');

Events

Listen to auth lifecycle events:

client.on('auth:login', (data) => {
  console.log('Logged in:', data.email);
});

client.on('auth:logout', () => {
  // Redirect to login page
});

client.on('auth:token-refresh', () => {
  // Token refreshed silently
});

client.on('auth:token-refresh-failed', () => {
  // Refresh failed, user needs to re-login
});

Server-rendered storefront sessions

Use request-scoped clients and HttpOnly, Secure, SameSite=Lax cookies for access and refresh tokens. A Server Component cannot write response cookies. Never give a read-only render an automatically rotating refresh token: the API would consume it while the browser retained its old cookie.

Roast restores only the access token into its rendering client. A separate Server Action reads the refresh cookie and calls auth.refresh(refreshToken) with automatic network retries disabled. It persists the response cookies before returning a non-secret expiry time. Browser Web Locks serialize this action across tabs; the action reads cookies only after acquiring the lock, so it also works with multiple server replicas. Page navigation with an expired access cookie goes through a session-renewal page before rendering the account. Active pages renew shortly before expiry. Only authentication rejection asks the customer to sign in again. A network or server outage preserves cookies and offers retry. The renewal page must not depend on successful catalog or cart reads, including its layout and metadata.

Keep tokens out of page props, URLs, analytics and logs. Logout must pass the stored refresh token explicitly if the rendering client only holds access. Single-use rotation and token-family revocation on replay remain enforced by the API.

See Next.js cookie write restrictions and origin-wide Web Locks.

Merchant account policy

Read getShopInfo().account.passwordMinLength (6 to 128) for registration, reset and password-change forms. The API enforces the current setting on each operation. Maximum password length is 128, including the part after byte 72.

account.requireEmailVerification and checkout.requireRegistrationApproval are independent gates. An account may need either or both. Pending responses have no tokens; display both outstanding steps when necessary. Current account activity and email-verification policy also apply to existing access and refresh sessions. An already issued token does not bypass a later administrative block.

Responses crossing a session change

SDK 2.0.3 rejects a response or retry from an older customer or cart context with status 409. A delayed refresh cannot sign a customer back in after logout, and an older logout cannot clear a newer login. Normal refresh rotation keeps the same customer context and the original request can still complete.

For React, use useAuth() to cancel old queries and discard customer data and customer-specific prices, including SSR seed data, on an identity change. Direct core API users must also clear their own UI caches. Use a separate client and cache for each server request. Never automatically replay a rejected write with another customer's credentials.

On this page