Token Management
Introduction
The Bearer Auth API provides the essential endpoints for comprehensive token management, enabling validation, refreshing, revocation, and deletion of access and refresh tokens to ensure secure and seamless user sessions.
{% content-ref url="https://app.gitbook.com/o/mRQMW2w7m6hBdzapMDC8/s/XrZ7fE7Ricr49KbZwHNK/" %} Authentication API
How it Works
The Bearer Auth API manages the lifecycle of access and refresh tokens used for user authentication. When a user logs in, the system issues a pair of tokens - an access token for authorizing requests and a refresh token for obtaining new access tokens when the current one expires.
The Bearer API allows validation of tokens, refreshing tokens to securely extend user sessions, and revoking tokens when needed to prevent unauthorized access. Additionally, the API supports retrieving all active tokens, or external tokens issues by Identity Provider and terminating specific sessions, helping improve security and user control across devices.
Token Management
SCAYLE provides robust token management features to ensure secure and seamless user sessions. Key functionalities include token validation, rotation with renewal, and revocation—each designed to enhance security, maintain session continuity, and reduce the risk of unauthorized access.
Periodic refresh token rotation improves security by regularly replacing refresh tokens, reducing the risk of unauthorized access if a token is compromised.
| Functionality | Description |
|---|---|
| Token Validation | SCAYLE provides endpoints to validate access tokens by checking their expiration and revocation status, ensuring that only valid tokens are accepted. |
| Token Rotation & Renewal | When an access_token expires, a valid refresh_token can be used to request a new token pair without user re-authentication, keeping sessions seamless. |
| Token Revocation | Tokens can be revoked automatically (e.g., on logout or password reset) or manually via API, preventing the use of compromised or expired tokens. |
Capabilities
| Endpoint | Use case |
|---|---|
| oauth/token/validate | Validates an given access token. |
| oauth/token | Refresh access token by exchanging the refresh token for a new pair of access and refresh tokens. |
| oauth/tokens | Retrieve all active access tokens for a specific user, primarily to display their active sessions across devices or browsers. |
| oauth/tokens/{accessTokenId} | Revokes the token tied to a given user ID, enabling actions like letting user logout of a specific session. |
| /oauth/token | Receive metadata for an given access token. |
Token Types
When a user authenticates via login, register or IDP redirect flows, SCAYLE returns a pair of tokens:
| Token | Format | Used For | Storage Recommendation |
|---|---|---|---|
| Access Token | JWT | Authorizing API calls and communication with Checkout Webcomponent | Securely in backend or HTTP-only cookie |
| Refresh Token | Opaque | Renewing access tokens without user re-login | Backend only; never exposed to frontend |
JSON Web Tokens
We strongly recommend using SCAYLE’s JWKS endpoint to parse and validate JWTs, which securely transmit trusted information between the Shop and SCAYLE in a compact, URL-safe format.
{
"typ": "JWT",
"alg": "RS256"
}
{
"aud": "5",
"jti": "f170861f44987a12d2991f48714de614a4cc1866326f16c582f4fd106907f36557542ab9c1bceb5a",
"iat": 1677680470.777426,
"nbf": 1677680470.777437,
"exp": 1680358870.75484,
"sub": "1",
"scopes": [],
"customerId": 11729551
}
Token Lifetime
Token lifetimes received from the login , login/guest or register endpoints (OAuth API) can be configured individually in the SCAYLE Panel when creating the API client.
For external Identity Providers (IDPs), the token lifetime of access and refresh tokens are always synchronized with the expiry dates provided by the IDP but they will never exceed the minimum or maximum token lifetimes defined by SCAYLE.
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.
| Token | Default Lifetime | Min | Max |
|---|---|---|---|
| Access Token | 30 days | 5 mins | 30 days |
| Refresh Token | 60 days | 1 day | 365 days |
Revoke Token
SCAYLE will automatically revoke tokens whenever any of the following endpoints are called:
auth/logoutauth/logout/redirectauth/password/send-reset-emailauth/password/update-by-hashoauth/tokens/{accessTokenId}
This ensures user sessions and tokens are securely invalidated during logout, password resets, or explicit token revocation.
External Token Validation
External access token validation ensures tokens issued by third-party identity providers (IDPs) remain trustworthy by periodically verifying their status beyond local checks.
Per default, the external token validation is disabled
External token validation in SCAYLE means checking with the identity provider (IDP) to confirm if an access token is still valid, beyond just relying on local expiry or revocation checks. When enabled, SCAYLE performs this validation once every 5 minutes per token by calling the IDP’s validation endpoint. The result is cached; if the token is invalid, all related tokens are revoked. If the IDP responds with an error, SCAYLE assumes the token is still valid, but a 401 response marks it as revoked.
Configuration
| Flag | Description |
|---|---|
isValidationTokenEnabled | Enables external token validation with the IDP; when disabled, only local checks are used. |
Supported Identity Provider
External token validation is only supported if the identity provider supports the required validation endpoint.
| Identity Provider | Supported |
|---|---|
| OIDC | Yes |
| MUFC | Yes |
| Auth0 | Yes |
| Keycloak | Yes |
| Salesforce | Yes |
| Apple | No |
| Yes | |
| Yes | |
| Okta | Yes |
