docs

Login & Registration

Customers sign in, register, and reset their password on one page, /signin, through the SCAYLE authentication component. In these three flows the Storefront Application V3 never receives a password. It mounts the component, trades the authorization code the component produces for tokens and the customer in one oRPC call, and merges the basket and wishlist the user built before signing in into the new signed-in session.

Why it matters

Every signed-in feature starts here: the account area, a basket tied to the customer, and checkout. The @scayle/storefront package owns the session and the basket and wishlist merge. Your application owns the page the customer lands on, the success toast, the reload of the customer props, and the extension points around them.

Try it

Try it: open the sign-in page

  1. Sign in with an existing account.
  2. Register a new account. Add ?register=true to the URL to open the form on the registration view.
  3. Reset a forgotten password. Select "Forgot your password?" underneath the form.
Recording of the sign-in page

What's included

  • Sign-in page: /signin, rendered by SignInController and SignIn.vue. It mounts the SCAYLE authentication component and switches it to registration when the URL carries ?register=true.
  • Password reset: the same page mounts the SCAYLE new-password component instead when the URL carries a ?hash= query parameter, which is the link in the password reset email.
  • Authorization code exchange: the exchangeAuthCode oRPC procedure. It trades the code for tokens, stores the customer on a new session, merges the basket and wishlist the user built before signing in, and returns only the access token.
  • Token refresh: the refreshAccessToken oRPC procedure. The authentication component calls it through a refresh hook that the application registers when the component starts.
  • Sign-out: useAuthentication().logout() and the logout oRPC procedure. The session ends and the access token is revoked at the Authentication API.
  • Return path: a redirectUrl query parameter that sends the customer back to the page they came from, and getSignInRoute() to build links that carry it.
  • Auth guard: a middleware, registered for every route under /account/*, that redirects a user without a signed-in session to /signin. See Pages: createAuthGuardMiddleware.
  • Sign-in analytics: a GA4 login event after sign-in and a sign_up event after registration.

What you can change

Configure

  • The OAuth client ID and client secret, and the session secret, through the STOREFRONT_OAUTH_CLIENT_ID, STOREFRONT_OAUTH_CLIENT_SECRET, and STOREFRONT_SESSION_SECRET environment variables. The Storefront CLI asks for all three when you set up your shop.
  • The identity providers and authentication methods the component offers, in the SCAYLE Panel.

Theme

  • The layout, heading, and spacing around the form in src/client/pages/SignIn.vue. The SCAYLE component renders the form itself.

Extend

  • Change the page title, meta tags, or the props the page receives by editing SignInController in src/server/controllers/signin.ts. It extends BaseController, so getTemplate(), getViewProps(), and beforeRender() are the hooks. getMeta() is private, so edit it in place.
  • Add your own fields to the customer by extending CustomerMapperService in src/server/services/mappers/customer-mapper.ts and augmenting Customer in src/shared/types/Customer.ts. Both files already add idHash, so follow that pattern.
  • Run your own code after sign-out by subclassing AuthFlowService and registering the subclass in the auth service slot of src/server/registries.ts. A slot is one entry in the service registry, see Extending the SDK.
  • Change the errors or middleware of the exchange, refresh, or sign-out procedures by replacing the auth key in src/server/api/index.ts.
  • Reload a shared prop that varies by customer segment after sign-in and sign-out.
  • Report your own sign-in surface to analytics through useAuthEvents() in src/client/composables/tracking/useAuthEvents.ts.

Replace

  • Swap the SCAYLE component for your own sign-in form or identity provider flow. You then write the form, the password handling, the token exchange, and the session write yourself, and SignIn.vue no longer handles the password reset link described on this page. Take this step only when the SCAYLE component cannot cover your sign-in method.

Constraints and limits

Permanent

  • All three flows run on /signin. There is no /register route. Registration is the same page with ?register=true, and the value must be the string true. With the path or path_except_default country selector, the route carries the country prefix, for example /us/signin. When the URL carries both ?hash= and ?register=true, the password reset step wins and the registration form does not appear.
  • Password reset has no route and no server code of its own. Both steps, requesting the email and setting the new password, run inside the SCAYLE component. See Reset a password.
  • Keep the pw-reset-url attribute on <scayle-auth>, and build its value by string concatenation. Without the attribute, the component builds the reset link from window.location, so the current query string ends up in the email. The Authentication API replaces {hash} and rejects any host other than the shop domain you set in the SCAYLE Panel. buildRoute is the wrong tool here, because it percent-encodes the literal {hash} placeholder and breaks the replacement.
  • redirectUrl accepts only a site-relative target that resolves on the same origin. An absolute URL, even one on your own host, a protocol-relative URL such as //example.com, and a backslash form such as /\example.com are all discarded. This prevents open redirects. The server and the client use the same check, but the fallback differs, see the next entry.
  • A customer who already has a session and requests /signin is redirected with a 302 on any visit that is not a partial reload, which is a request for only some of the page's props. The target is the valid redirectUrl, or /account/orders when there is none. After a sign-in on the page itself, the client navigates to the valid redirectUrl, or to the home page when there is none.
  • On the Checkout page, a successful sign-in only reloads the session props. The checkout web component manages the navigation after sign-in, so the success toast and the redirectUrl navigation are skipped.
  • Sign-out ends the session before it revokes the access token, and a failed revocation does not fail the sign-out. See Sign out.

Known limitations

  • A failed token exchange or customer profile request ends the session. The customer has to sign in again, and the basket and wishlist the user built before signing in are not merged. See Sign in for the answers each failure gives.
  • A failed basket merge stops the page from completing the sign-in, and a failed wishlist merge never does. See Sign in.
  • A failed token refresh through the authentication component ends the session, and the customer has to sign in again. A rate limit and a missing refresh token keep the session, see How a token gets refreshed.
  • When the sign-out call fails, the customer sees an error toast and stays signed in. See Sign out.

How it works

A user reaches /signin in one of two ways. The auth guard sends them there from an /account/* page and appends the original path as redirectUrl, or they follow a link you built with getSignInRoute().

Sign in and register

SignInController renders the SignIn page with three props: showRegistration, a valid access token from the session (or undefined for a user), and the head meta with noindex,follow. SignIn.vue loads the SCAYLE script, then useCheckoutWebComponent waits for the script's scayle.auth.ready event and starts the authentication API with your OAuth client ID, the current access token, and two hooks, one for the code exchange and one for the token refresh. The page renders the component only after that start finishes.

The customer completes the form inside the component. The component hands the authorization code to the exchange hook, and the hook calls the exchangeAuthCode procedure on your server. Sign in and sign out shows the sequence and what the procedure does.

After auth:success, useCheckoutWebComponent runs authenticated(source) from useAuthentication and tracks the event once that finishes. authenticated shows a success toast chosen by the source (login, register, new-password, or login-guest), reloads the customer, basket, wishlist, and promotions props, and navigates with a replace to the valid redirectUrl or the home page. The customer the procedure stores carries the customer's segments in customer.segments, see Customer Segments.

Reset a password

The email link opens /signin?hash=<hash>. SignIn.vue reads hash from the query string and mounts <scayle-auth-new-password> instead of <scayle-auth>. When the customer sets the new password, the component reports the new-password source and the same authenticated(source) step runs.

Refresh a token

The application never calls refreshAccessToken on its own. The authentication component calls the refresh hook when it needs a new access token, and the hook calls the refreshAccessToken procedure. When the component hands the hook an authorization code instead, the hook calls exchangeAuthCode with it. How a token gets refreshed covers what the procedure and the server-side services do.

Sign out

logout() in useAuthentication signs the customer out on the server and in the browser. The customer stays on the current page. On an /account/* page, the auth guard answers the reload with a redirect to sign-in. Sign out lists the steps in order.

The sign-out button in the account popover and the mobile sidebar both call logout(). The call fires no analytics event.

Setup

Sign-in ships with the Storefront Application V3. The /signin route, the oRPC procedures, and the return path handling are already registered.

  1. Set STOREFRONT_OAUTH_CLIENT_ID and STOREFRONT_OAUTH_CLIENT_SECRET to your OAuth client ID and client secret. .env.example lists the names.
  2. Set STOREFRONT_SESSION_SECRET to a string of at least 32 characters.
  3. Start the application and open /signin.

You know it worked when the SCAYLE sign-in form appears under the page heading.

Configuration

SCAYLE Panel

You configure the identity providers and the authentication methods the component offers in the SCAYLE Panel. See Configure identity providers in SCAYLE Panel for the setup steps.

Storefront Application

FieldTypeDescription
oauth.clientIdstringThe OAuth client ID. The page passes it to the authentication component as an integer, so it must be a number written as a string. Env: STOREFRONT_OAUTH_CLIENT_ID.
oauth.clientSecretstringThe OAuth client secret, used on the server during the code exchange. Env: STOREFRONT_OAUTH_CLIENT_SECRET.

The session.secret, session.ttl, and session.cookieName fields are covered in Session and Authentication.

Customization guides

You end up with a link that opens /signin and brings the customer back after sign-in.

  1. Import getSignInRoute and routes from @shared/routes. Its signature is getSignInRoute(redirectUrl: string = routes.home, register: boolean = false): string.
  2. Pass the return path as the first argument. Use $page.url for the current page, or a localized route such as localizeLink(page.props.storefront, routes.basket), because route constants carry no country prefix.
  3. Pass true as the second argument to open the registration form.
  4. Use the result as the link target.

You know it worked when the link points to /signin?redirectUrl=<current page>, with register=true added for the second button, and the customer returns to that page after signing in. The helper omits redirectUrl when the return path is exactly /. A country-prefixed home page such as /us stays in redirectUrl. When you pass a /signin URL that carries its own redirectUrl, as $page.url does on the sign-in page, the helper unwraps the inner value so the customer does not loop back to sign-in. A bare /signin becomes the home page.

Run your own code after sign-out

You end up with your own code that runs after every sign-out of a signed-in customer, with the session already destroyed.

  1. Subclass AuthFlowService and override logout(). Call super.logout(), because the base method destroys the session and revokes the token. If you skip it, the logout procedure no longer ends the session and the customer stays signed in.
  2. Point the auth slot in src/server/registries.ts at your subclass.

You know it worked when your code runs on every sign-out of a signed-in customer. Move the class into its own file next to your other services once it grows past a few lines.

Best practices

Sign out through useAuthentication().logout()

Calling the logout procedure directly ends the session and revokes the access token, but nothing on the client changes. The composable also clears the checkout tokens, the history key, and the customer, basket, wishlist, and promotions props, so the page does not keep showing the previous customer.

Keep the analytics call when you replace the page

The login and sign_up events come from useCheckoutWebComponent through useAuthEvents().trackAuthSuccess, which runs for the auth:success event of the SCAYLE component. A replacement sign-in surface needs its own call to trackLogin() or trackSignUp() once the customer is authenticated, or those events stop without any error.

Capture the basket and wishlist keys around the session change

If you write your own exchange handler, read the basket and wishlist keys before session.regenerate(customer) and again after you store the customer on the session. Regenerating the session and storing the customer give the customer new keys, so a merge that uses keys captured afterward runs against keys the pre-sign-in items do not belong to. Nothing throws, and the customer sees an empty basket and wishlist after signing in.

Read the basket key with services.basket.getBasketKey(session) and the wishlist key with mappers.wishlist.getWishlistKey(session), which calls getWishlistKey of your WishlistMapperService. The procedure calls getWishlistKey once before and once after the session changes. The SDK's auth.exchangeAuthCode procedure follows this order and runs the basket merge and the wishlist merge at the same time.

Troubleshooting

The sign-in form never appears

Issue: /signin shows the page heading and an empty area where the form belongs.

Possible causes: The page renders the component only after the authentication API has started. The start needs the SCAYLE script to load and fire scayle.auth.ready, and it needs a usable oauth.clientId.

Solution:

  1. Open the browser console and look for the log entries Checkout OAuth client ID not configured or Failed to initialize the checkout auth API.
  2. Confirm that STOREFRONT_OAUTH_CLIENT_ID is set and holds a number.
  3. Check the network panel for the SCAYLE web component script request and for anything that blocks it, such as an ad blocker or a content security policy.

Prevention: Complete the Setup steps before you first open /signin in a new environment.

A customer completes the form but is not signed in

Issue: The component accepts the credentials, but the page shows no success toast and the customer stays signed out.

Possible causes: The exchangeAuthCode procedure failed. The Authentication API rate-limited the exchange, the token exchange or the customer profile request failed, or the basket merge failed.

Solution:

  1. Search the server logs for Failed to exchange authorization code, or for Auth API rate-limited the code exchange for a rate limit.
  2. Read the err field of the entry for the upstream cause. A failed basket merge does not write the first two messages. The browser console shows Failed to exchange auth code for it.
  3. Ask the customer to sign in again.

Prevention: None on your side for an upstream failure.

A signed-in customer is signed out without clicking sign-out

Issue: A customer who was signed in lands on the sign-in page, or sees the signed-out header, after some time on the site.

Possible causes: The token refresh failed, see the token refresh limitation above. A call to the Customer Account API can also end the session when it is rejected again after a token refresh, or when the refresh answers with a 401. The session can also reach its session.ttl, or the refresh token can reach its own lifetime.

Solution:

  1. Search the server logs for Failed to refresh access token.
  2. Read the err field of the entry for the upstream cause, for example a revoked or expired refresh token.
  3. Ask the customer to sign in again.

Prevention: None on your side.

Reference

SCAYLE documentation