Integrate

What to Expect

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

Understand best practices for token lifecycle management
Validate the current access token
Use refresh tokens to maintain user sessions
Retrieve active access tokens for a user
Revoke a single access token for a user

Prerequisites

Accessing API Endpoints

For endpoint access, use the following host:
https://{{tenant-space}}.auth.scayle.cloud

Creating API Clients

Refer to the Authenticate Guide for more information on how to access Scayles Auhentication APIs

You can find more details in the authenticate section.

Integrate

Validate Access Token

Endpoint: https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/token/validate

SCAYLE provides an endpoint to validate the internal access token. This ensures the token is still valid and has not expired or been revoked. Make sure to pass the access token in the header as Authentication Bearer

The Authentication Service automatically validates token expiration with every request made by the Checkout Webcomponent. Additionally, the Checkout Service periodically checks whether the token has been revoked.

Behavior:

Returns 200 OK if the token is valid
Returns 401 Unauthorized if the token is invalid or expired

Refresh Access Token

Endpoint: https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/token

When an access token expires, you can use the refresh token to obtain a new pair of tokens by using the refresh_token grant type.

When a refresh token is used to obtain a new pair of access token and refresh token, the access token's expiration date is reset to the default. However, the expiration date of the refresh token remains unchanged and will continue as originally issued.

Never expose the refresh token on the frontend. It must be stored and used through the Shop backend.

Request Example:

{
  "grant_type": "refresh_token",
  "refresh_token": "your_refresh_token"
}

Response Example

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 2678400,
  "token_type": "Bearer"
}

List Active Access Tokens

Endpoint: https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/tokens

To retrieve all active tokens for a specific user_id, you can call the tokens endpoint. This allows users to e.g. view their active sessions across different devices or browsers.

Revoke Active Access Token

Endpoint: https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/tokens/{accessTokenId}

This endpoint requires a valid Bearer access token in the Authorization header and will revoke the token associated with the provided user ID. This is useful, for example, when allowing a user to log out of a specific session after displaying all active sessions using the endpoint above.

List Token Detail

Endpoint: https://{{tenant-space}}.auth.scayle.cloud/v1/oauth/token

The Token Detail endpoint provides metadata for a specific access token, including its ID, IP address, user agent, creation and expiration times. If linked to an external identity provider (e.g., Okta), it also includes the external access token, provider key, and related timestamps. This is useful for tracking session details and managing token lifecycles.