Behio Storefront SDK
Getting Started

Authentication

Customer registration, login, and token management

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.

Business sign-up (company id and VAT ID)

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.

Company details alone are an invoice choice. They never apply for a partner (wholesale) account; that is the separate applyForB2b flag below.

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',
});

Partner (B2B) account application

Since SDK 2.40.0 a registration can also apply for a partner account that the merchant approves. Offer the control only when shop.b2b?.approvalMode is not OFF, the shop is not partners only (b2bMode) and shop.b2b.applicationFormSlug is null. With a form slug, link to that form instead.

const {data, error} = await client.auth.register({
  email: '[email protected]',
  password: '...',
  company: 'ACME s.r.o.', // required with applyForB2b
  country: 'CZ',
  applyForB2b: true,
  locale: 'cs',           // language of the decision e-mail
});
if (data?.pendingApproval) {
  // Mode BLOCKED: no tokens. The account logs in after the merchant approves.
} else if (data?.b2bApplicationStatus === 'PENDING') {
  // Mode ACCOUNT_FIRST: logged in at regular prices, the application waits.
}

The full flow (modes, statuses, the account banner, the merchant's own form, company register prefill) is in B2B registration and approval.

Login

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

A refused login is 401. Read the key with errorCode(error) and give these their own sentence; everything else is "wrong e-mail or password":

KeyMeaning
be.storefront.emailVerificationRequiredThe e-mail address is not confirmed yet.
be.storefront.b2bApprovalPendingA partner applicant of a shop that locks the account until approval.
be.storefront.b2bApplicationRejectedThe partner application of a locked account was declined.

The API reveals them only after a correct password.

Behio e-mails link to fixed addresses on the shop's domain:

AddressSent byPage does
/verify?token=...welcome e-mail, partner account approvalclient.auth.verifyEmail(token)
/reset-password?token=...password reset, partner account approval of an account created by the approval ("set your password")client.auth.resetPassword(token, newPassword)
/accountpartner account approval with nothing left to dothe customer account

A token works once. Confirm it on the server and show the result in the first HTML; a missing route here means a dead button in the customer's inbox.

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. checkout.requireRegistrationApproval covers the shops where EVERY registration waits for the merchant. A mixed shop keeps it false and gates only partner applicants; read b2b.approvalMode for that (B2B registration and approval). 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