Authenticate

Introduction

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

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.

javascript

Copy

<!-- Include the script before initializing Checkout Authentication Component -->
<script src=y"https://{tenant-space}}.checkout.api.scayle.cloud/frontend/checkout-wc/js?appId={{shop}}"></script>

<!-- Continue with Initialize the Authentication Component in Shop-Side Authentication  -->

<script>
  window.addEventListener("scayle.preloader.completed", () => {
    // Your checkout auth initialization code
  });
</script>

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.

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:

js

Copy

const auth = window.scayleCheckout.auth.V3;

auth.init().then(isAuthenticated => {
  if (isAuthenticated) {
    console.log('User is already authenticated');
  } else {
    console.log('User needs to log in');
  }
});

Available Pre-Selected Forms (Variants)

You can control the default form shown by setting the variant attribute:

Default (Guest View)

html

Copy

<scayle-auth></scayle-auth>

Login View

html

Copy

<scayle-auth variant="login"></scayle-auth>

Registration View

html

Copy

<scayle-auth variant="register"></scayle-auth>

Handle Login Success

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

js

Copy

`auth:success`: Emitted when authentication is successful
  
  {
    accessToken?: string;
    source: 'login' | 'login-guest' | 'register' | 'new-password';
  }

javascript

Copy

const auth = window.scayleCheckout.auth.V3;

// Listen for successful authentication
auth.events.listen('auth:success', event => {
  console.log('Authentication successful', event);
});

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

js

Copy

window.scayleCheckout.auth.V3.getAccessToken();

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:

Copy

`auth:error`: Emitted when authentication fails
  
  {
    source: 'login' | 'login-guest' | 'register' | 'new-password';
    error: {
      errors?: Record<string, string>;
      message?: string;
      errorKey?: string;
      retryAfterSeconds?: number;
    }
  }

java

Copy

const auth = window.scayleCheckout.auth.V3;

// Listen for authentication errors
auth.events.listen('auth:error', error => {
  console.error('Authentication error', error);
});

Handle Passwort 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:

html

Copy

<scayle-auth-new-password hash="{HASH}"></scayle-auth-new-password>

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:

Copy

window.scayleCheckout.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

Copy

<scayle-auth>
  <!-- Content above the authentication form -->
  <div slot="slot-auth-top">
    <p>Welcome to Express Checkout – Please log in to continue.</p>
  </div>

  <!-- Content below the authentication form -->
  <div slot="slot-auth-bottom">
    <small>By continuing, you agree to our terms and conditions.</small>
  </div>
</scayle-auth>

Single-Sign-On

The Authentication Component supports integration with Identity Providers across login, guest checkout, 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.