Authenticate

Introduction

This guide explains how to integrate the Authentication Web Component (<scayle-auth>) within the Checkout Webcomponent or indiviudally on shop side.

Retaining active user sessions is not supported. If you're migrating from the deprecated session-based authentication or previously used SCAYLE Authentication APIs, users will be required to log in again when accessing the Checkout for the first time after the migration.

What to expect

By the end of this guide, you will be able to

Load and initialize the Authentication Component
Handle Successful Logins
Handle Authentication Errors
Load and initialize the Password Reset Component
Handle Logouts via the SDK and self built Buttons
Configure Optional Functionalities

Prerequisites

To implement a complete authentication flow using the Authentication Component the following steps are required.

Define Entry Point for Authentication

Choose a dedicated entry point where users can initiate authentication - this could be a standalone route (e.g., /login) or a modal dialog that opens the login form. Ensure this entry point is easy to find and accessible throughout your site.

Set Page for Password Reset

Create a secure route to handle password resets. This page should only be accessible via a reset link sent in the password reset email (which contains a hash parameter). Do not expose this page through your main navigation.

Add a Logout Button

Display a logout (sign out) button only when the user is authenticated. Make sure it's clearly visible and easy to access.

Add Checkout JavaScript Bundle

Before using the Authentication Web Component, make sure to include the necessary Checkout Web Component JavaScript bundle.

You can find more details in the initial checkout setup section.

Before trying to access window.scayle.auth.V3 make sure to wait for the scayle.auth.ready event. See an example below

Checkout-Side Authentication

SCAYLE Checkout automatically renders the <scayle-auth> component if no access token is provided by the shop. If an access token is provided (and its valid), then the user will be automatically forwarded to the Checkout.

Task	Description
Integration Effort	None. SCAYLE Checkout automatically renders the `<scayle-auth>` component if no access token is injected by the Shop.
Handle Login Scenarios	Valid Access Token: If a valid token was stored in SCAYLE's local cache, the user is seamlessly redirected to the checkout Invalid Access Token: If the token is not provided or invalid, the user is automatically redirected to the login form to authenticate before proceeding.
Handle Token Refresh	Expired Access Token: In case the access token is expired, the Authentication SDK will automatically refresh the token. Expired Refresh Token: If the Refresh token is expired or revoked, the user is automatically redirected to login form

Shop-Side Authentication

The Shop-Side Authentication Setup allows you to manage user authentication directly within the Shop, providing full control over the login or registration flow before users reach the Checkout. By integrating the SCAYLE Authentication Component and initializing it on page load, the Shop can verify existing sessions, render appropriate login or registration forms, and handle authentication events such as login success or token expiration - all without any backend involvement.

Initialization

Use the global init method to check if the user is already logged in:

Available Pre-Selected Forms (Variant and Variants)

The displayed forms and the default form can be controlled using attributes:

variant – defines the form shown first.
variants – an array of all available options (e.g. ["login", "register", "guest"]).

When no attributes are provided, both login and registration forms are available by default.

Login View First

Registration View First

Login View First with Guest Option

Displays the login form first.
Options available: login, registration, and guest.

Registration View

Handle Login Success

Listen for the auth:success event to detect when a user successfully logs in:

The Authentication SDK already holds a valid access token, which you can retrieve using:

Handle Errors

The SDK automatically handles token refresh using its internal refreshToken method - no backend involvement is required.

However, the Shop should still prepare for cases the refresh attempt fails and decide how to respond e.g., in case of network errors, revoked refresh tokens, or server-side authentication issues.

❌ Authentication Failed:

Handle Password Reset

To support password reset flows, the <scayle-auth-new-password> component allows users to enter their email address. When the user initiates a reset, they receive a link containing a hash URL parameter.

To handle the password reset, extract the hash from the URL and pass it to the new password component:

Handle Logout

Build your own frontend UI for the logout action (e.g., a button placed anywhere in your application). To log out the user, use the SDK’s logout() method and optionally listen for logout-related events.

Call the logout method provided by the Authentication SDK:

window.scayle.auth.V3.logout()
  .then(() => {
    console.log('Logout successful');
    // Optional: Redirect user or update UI
  })
  .catch(error => {
    console.error('Logout failed', error);
    // Optional: Show error message to the user
  });

You can also listen for logout-related events if needed, for example, to trigger UI updates or redirects after logout.

Optional Configurations

Dynamic Input Fields

The Authentication Component supports a set of dynamic, configurable fields for both registration and guest user login. These fields can be activated or customized via the SCAYLE Panel.

The Authentication Component will automatically retrieve the necessary configuration

You can find more details in the dynamic fields section.

Express Checkout

When using Express Checkout, the <scayle-auth> component can be fully customized by injecting content into predefined slots. This enables you to tailor the login and registration experience to match your storefront’s design—while maintaining full compatibility with SCAYLE’s Express Checkout flow.

Once the Express component is loaded, follow the Express Checkout Integration Guide for detailed setup instructions. The Authentication Component will automatically retrieve the necessary configuration and render all available Express SDKs without requiring any additional integration effort.

You can find more details in the express checkout section.

Add Custom Elements

Use Dynamic Slots to insert custom elements (e.g., banners, messages, legal text) above or below the default authentication forms

Single-Sign-On

The Authentication Component supports integration with Identity Providers across login and registration forms.

Once configured, the Authentication Component automatically retrieves the relevant settings and displays the available Button to redirect users to the Identity Provider - no additional integration steps are required.

The Single Sign-On (SSO) button in the Authentication Component adopts the Checkout buttonSecondary styling, following branding guidelines outlined under CSS variables.