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 |
|
Handle Login Scenarios |
|
Handle Token Refresh |
|
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.
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.