Integrate

What to Expect

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

• Register a new customer
• Enable Guest User login
• Implement User login
• Properly log Users and revoke token
• Handle password reset flows

Prerequisites

Middleware for Mobile Applications

As a Backend-middleware layer is needed to interact with the Authentication API, a proxy-endpoints for the mobile application are required. The Application can not work directly with the Authentication APIs as those endpoints are basic-auth protected and the ability to change the credentials on the fly is necessary without having to ship a new app version through the app stores.

Accessing API Endpoints

For endpoint access, use the following host

Copy

Creating API Clients

Before interacting with the Authentication API, you must create an API Client to obtain your client_id and client_secret. These credentials are essential for authenticating your requests:

Copy

You can create an API Client in SCAYLE Panel under Shops ➜ [Shops] ➜ Storefront ➜ API Keys.

Handle Access and Refresh Tokens

After a successful customer login or registration, your application will receive an initial set of tokens: an access token and a refresh token.

Copy

The access token can then be used to load the Checkout Webcomponent as authorization header to call the API endpoints.

The refresh token, is a longer-lived token that can be used to obtain a new access token when the current one expires, ensuring a seamless user experience without requiring reauthentication.

Integrate

In case more customer related information should submitted (e.g. birthdate), the Authentication API can be used to register the customer and the Admin API to update the customer asynchronously.

Registration

To register a new customer, create a registration form in your shop frontend with the following fields:

• Gender (values: m, f, d , n )
• First name
• Last name
• Email address
• Password

Customer Login

Create a login form in your shop frontend with the following fields:

• Email address
• Password

Guest User Login

Enable guest checkout by creating a guest login form with:

• Gender (values: m, f, d, n)
• First name
• Last name
• Email address

Logout

If the customer wishes to log out, they can use the designated logout endpoint. This endpoint can also be used by the Shop itself to revoke the currently active access token and refresh token, even while the customer is still authenticated with a valid access token.

After logging out, the user should be redirected to a specified callback URL. Please use the shop ID and sign the JWT with the shop secret. Finally, the Authentication Service will attempt to redirect the user to the provided callback URL.

Password Reset

Send Password Reset Email

• Provide a form in the frontend where customers enter their email to request a password reset.
• In the Shop Backend, utilize the Authentication API endpoint to trigger the sending of the password reset email to the customer.
• The route and structure of the reset_url can be customized freely. This URL should link to the page created in the subsequent step. It is essential to include the {hash} placeholder in the URL.
• The Authentication API will insert the password reset token into this placeholder before sending the Email

Update Password Using Reset Token (Hash)

• At the reset URL, provide a form where customers can enter a new password. Customers will be sent to this form after clicking the button or link in the password reset email.
• Extract the password reset token (hash) from the URL and send it, along with the new password, to your backend.
• Your backend forwards this data to the Authentication API to finalize the password reset.

Password Validation Service

The Password Validation Service enables external password verification during customer migration to SCAYLE, allowing password checks without needing to import hashes. This is useful for seamless migration, as it lets SCAYLE delegate password verification to an external system. Upon successful validation, passwords can be rehashed and stored securely on SCAYLE’s side, requiring only a single successful login for each customer to complete the migration.

Prerequisites

• SCAYLE must enable this feature for your shop upon request
• Customers must be flagged as having an external password for the validation flow to be triggered.

Implementation Requirements

• Deploy an HTTP service capable of handling standard shop traffic and accepting inbound requests from SCAYLE’s infrastructure.
• You may restrict inbound traffic by IP; please contact your SCAYLE Account Manager for allowed IP ranges.
• Authentication: Basic Auth is required. Provide SCAYLE with the credentials for access.

Response Specification

Your service must comply with SCAYLE’s expected response schema to process checkout password validation correctly. Full technical details should be coordinated with your SCAYLE Account Manager.