docs
  1. Checkout Guide
  2. Authentication & Accounts
  3. Authentication API
  4. Single Sign-on
  5. Integrate

Integrate

What to Expect

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

  • Create JTW and Redirect URL
  • Redirect Users to Identity Provider
  • Handle Redirect Callbacks
  • Exchange Authorization Codes for Tokens

Prerequisites

Whitelisting Login & Logout URL

To enable communication between your Identity Provider and SCAYLE's Authentication API, you must whitelist the following URLs on the Identity Provider side. \

  • Login: https://{{tenant-space}}.auth.scayle.cloud/v1/auth/external/callback
  • Logout: https://{{tenant-space}}.auth.scayle.cloud/v1/auth/logout/callback


The Authentication API requires access to:

  • Authorization Code
  • Refresh Token

Integration

When a user selects “Login with SSO” on the Shop side, the user is redirected to SCAYLE’s Authentication API, which then routes them to respective Identity Provider, such as Google or Microsoft. After the user logs in successfully with the IDP, they are redirected back to the SCAYLE Authentication API, which stores the IDP’s access and refresh tokens and generates an authorization code. The user is then forwarded to the shop via a callback URL, carrying this authorization code. The shop backend uses the code to request SCAYLE’s Authentication API for access and refresh tokens that can be used to communicate with SCAYLE's Checkout Component.

Handle Login

Redirect to Identity Provider

To initiate authentication, redirect the user to the Authentication API

https://{{tenant-space}}.auth.scayle.cloud/v1/auth/external/redirect?shopId=...&jwt=...

Either generate a link, pointing to the Authentication API directly, or provide a 302 redirect flow upfront, if necessary.

<a href="https://{{tenant-space}}.auth.scayle.cloud/v1/auth/external/redirect?shopId=...&jwt=...">
    IDP Login
</a>

The URL must include the shopId and aigned JWT with The redirect URL after login callbackUrl , The identifier of the configured IDP idpKey , and the OAuth clientId .

const jwt = require('jsonwebtoken');

const payload = {
    callbackUrl: 'https://localhost:8080/account-area',
    idpKey: yourCustomIdpIdentifierCode,
    clientId: clientId,
    iat: Math.floor(Date.now() / 1000), // Current timestamp in seconds
    exp: Math.floor(Date.now() / 1000) + (15 * 60) // Expiry: Current time + 15 minutes in seconds
};

const secret = 'yourShopSecretKey';
const token = jwt.sign(payload, secret, { algorithm: 'HS256' });

The Authentication API validates the JWT using the shopSecret, then redirects the user to the configured IDP’s login page.

Callback to Authentication API

After successful authentication, the IDP redirects the user to the Authentication API, which stores the access and refresh token and generates an Authentication Code for the shop.

Redirect to CallbackUrl

The user will be then redirect by the Authentication API back to the callbackUrl, which was initially defined in the JWT. SCAYLE will enrich the callbackUrl with the following parameter

ParameterDescription
code
  • The Authorization Code that is needed to fetch the access- and refresh- tokens.
state
  • Encoded original JWT payload

Decode CallbackUrl Parameters

Fetch the code from the request and use it to request tokens in the next step

onst queryString = require('querystring');

const authCode = req.query.code || '';
const state = req.query.state ? JSON.parse(Buffer.from(req.query.state, 'base64').toString()) : {};

Request Tokens

Use the code to request access and refresh tokens from the Authentication API

curl -X POST --location 'https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {base64Encode({client_id}:{client_secret})}' \
--data-raw '{
  "grant_type": "authorization_code",
  "code": "..."
}'

The access and refresh token can be then used in communication with Scayles Checkout Component.

Handle Logout

When SCAYLE's logout endpoints are called, the system will revoke both access and refresh tokens, attempt to revoke the token with the Identity Provider (if supported), and then redirect the user to the specified callbackUrl .

Logout User

Logout User with Redirect

Either generate a link, pointing to the Authentication API directly, or provide a 302 redirect flow upfront, if necessary.

<a href="https://{{tenant-space}}.auth.scayle.cloud/v1/auth/logout/redirect?shopId=...&jwt=...">
    Logout
</a>

The JWT payload needs to contain the callbackUrl, and a tokenId.

The tokenId is not the same as the Access Token itself. If you want to revoke a token you received from the login or register endpoints, you can get the Access Token ID by decoding the Access Token's JWT payload and extract the jti property, which is the ID. The user will then be redirected back to your callbackUrl.

Token Management

On top of regular authentication capabilities, SCAYLE offers advanced token management such as \

  • Validating access tokens to check for expiration or revocation.
  • Refreshing tokens to obtain new access and refresh tokens using the refresh_token grant.
  • Listing active tokens to view user sessions across multiple devices.
  • Deleting individual active tokens by ID to revoke specific sessions.


For further details on advanced token functionalities, please refer to the Token Management Guide.

You can find more details in the token-management section.

The relevant Token Management APIs are available under the Authentication APIs section

Token Management (Bearer Auth)

Next up
Configure