Web Service Session Optimization

Understanding

Session integration optimization is a feature that caches recent verification results to avoid repeating the validation of the SUAT (Security User Access Token) for every request or action. Upon the initial entry, the SUAT is verified via the Accounts authentication API (/auth/v5/user_token/check), and the result is stored in the cache. For subsequent requests from the same user, the authentication API call is skipped if the cache is valid. This allows you to maintain the latest authentication status while minimizing authentication API calls.

The integration method is divided into two types depending on the rendering environment. The SSR environment (backend), where pages are rendered on the server, uses server-side Redis as the verification cache, while the CSR/SPA environment (frontend), where screens are rendered in the browser, uses Session Storage as the verification cache.

Applicable Environments

The verification API and purpose are the same; only the cache storage and key differ. You can choose the track that fits your service's rendering method.

Components

Operating Principle

Upon initial entry, the SUAT is verified via the Auth API and the result is stored in the cache. For subsequent requests with the same SUAT/session, if the cache is valid (within 5 minutes), the Auth API call is skipped; re-verification occurs only if the cache is missing, expired, or the SUAT has changed. This reduces redundant verification calls for the same SUAT, improving response performance.

SSR stores verification results in server-side Redis, allowing multiple requests and multiple servers to share the cache. CSR stores them in the browser's Session Storage, which persists through refreshes (F5) but is deleted when the tab is closed. Regardless of the method, it is recommended to use hash values such as SHA-256 rather than using the raw SUAT as the cache key directly.

Integration Guide

Prerequisites

These are the common requirements for both SSR and CSR. Detailed preparations for each method are provided in their respective [Development] tracks.

Basic Verification Flow

When a request or action occurs, the SUAT is extracted to check the verification cache; if the cache is valid, the Auth API call is skipped. The Auth API is called and the result is stored in the cache only when the cache is missing, expired, or the SUAT has changed. Both SSR and CSR follow the decision flow below.

Items to Decide Before Starting

Decide on the following items before service integration. The cache structure and authentication failure handling method will vary depending on the results.

Environment Classification Guide

The applicable environment varies depending on the service's rendering method and the availability of cache storage.

Integration Checklist

Check the items below before integration.

Development

SSR Integration (Backend)

This is for integration in environments where pages are rendered on the server. The server extracts the SUAT included in the request, decides whether to call the Authentication API based on the Redis validation cache, and if the cache is valid, renders the page without re-validating.

Prerequisites

• accounts.onstove.com/login must have a SUAT authentication token issued to the Client.
• The SSR service must be able to receive the SUAT Cookie included in the request header.
• /auth/v5/user_token/check API must be integrated to verify SUAT validity.
• A Redis cache must be configured to store validation results, using a secure key to identify the SUAT and a TTL of 300 seconds (5 minutes).
• Implement logic to skip the authentication validation API call if the Redis cache exists, and only re-validate if it is missing or expired.

Development Flow

Perform user authentication using the SUAT held by the Client upon entering the SSR service. Cache the validation result in Redis to reduce repeated validation calls for the same SUAT.

1. Extract SUAT from the request header when entering the SSR service.
2. Query the Redis validation cache using a SUAT-based cache key (e.g., SUAT_CHECK:{SUAT_HASH}).
3. If the cache exists and is valid, process the request without calling /auth/v5/user_token/check.
4. If the cache is missing or expired, call /auth/v5/user_token/check to verify the SUAT.
5. If validation is successful, store the result in Redis and set the TTL to 300 seconds (5 minutes).
6. Subsequent requests with the same SUAT will reuse the cache, improving SSR service response performance.

Troubleshooting

These are the handling methods for each response code. Please refer to the API & SDK Reference menu for detailed response code and message specifications.

Sample Code

This is an example of comparing the requested SUAT with the cached SUAT in a Spring-based SSR service and calling the Authentication API only when the value changes. In a multi-server environment, please use a shared Redis as a cache instead of a local session to share validation results across servers.

CSR Integration (Frontend)

This is for integration in an SPA environment where the browser renders the screen. The decision to call the authentication API is determined by the Session Storage verification cache; if the cache is valid, the request is processed without re-verification.

Prerequisites

• accounts.onstove.com/login must be used to issue a SUAT authentication token.
• The SPA service must be able to verify the validity of the user token via the POST /auth/v5/user_token/check API.
• You must be able to use Session Storage to store verification results.
• The verification cache is stored in Session Storage using the STOVE_USER_TOKEN_CHECK key and managed with a TTL of 300 seconds (5 minutes).
• It is recommended to handle all API calls through common logic (Interceptor or API Wrapper) that checks the verification cache.

Development Flow

Check the verification cache in Session Storage upon initial service entry and for every user action. If the cache is valid, the authentication API call is skipped, and the cache is maintained even after a refresh (F5).

1. Upon initial service entry, verify the user token validity via POST /auth/v5/user_token/check.
2. Once verified, store the verification time (verifiedAt) and expiration time (expireAt) in Session Storage(STOVE_USER_TOKEN_CHECK).
3. Before calling an API due to a user action, check the verification cache in Session Storage.
4. If the cache is valid (within 5 minutes), skip the authentication API call and process the request.
5. If the cache has expired or is missing, call the authentication API again to verify, then update the Session Storage.
6. Since Session Storage is maintained even when the browser is refreshed (F5), no re-verification is performed if the cache is valid.

Troubleshooting

These are the handling methods for each response code. Please refer to the API & SDK Reference menu for detailed response code and message specifications.

Sample Code

This is an example of checking the Session Storage verification cache to skip the authentication API call if valid, and performing token verification via a common wrapper before API calls.

const STORAGE_KEY = "STOVE_USER_TOKEN_CHECK";
const CACHE_TTL = 5 * 60 * 1000; // 5분

/**
 * 토큰 유효성 검증. 캐시가 유효하면 API 호출을 생략해요.
 */
async function validateUserToken() {
    const cache = getTokenCheckCache();

    // 캐시가 유효하면 검증 API 호출 생략
    if (cache && cache.expireAt > Date.now()) {
        console.log("Skip /auth/v5/user_token/check");
        return true;
    }

    // 캐시가 없거나 만료 시 검증 API 호출
    const response = await fetch("/auth/v5/user_token/check", {
        method: "POST",
        credentials: "include"
    });

    if (!response.ok) {
        throw new Error("Invalid User Token");
    }

    saveTokenCheckCache();
    return true;
}

/**
 * 검증 결과를 Session Storage에 저장
 */
function saveTokenCheckCache() {
    const now = Date.now();
    sessionStorage.setItem(
        STORAGE_KEY,
        JSON.stringify({
            verifiedAt: now,
            expireAt: now + CACHE_TTL
        })
    );
}

/**
 * Session Storage에서 검증 캐시 조회
 */
function getTokenCheckCache() {
    const value = sessionStorage.getItem(STORAGE_KEY);
    if (!value) {
        return null;
    }
    try {
        return JSON.parse(value);
    } catch {
        sessionStorage.removeItem(STORAGE_KEY);
        return null;
    }
}

/**
 * API 호출 전 토큰 검증을 수행하는 공통 래퍼
 */
async function requestApi() {
    await validateUserToken();
    return fetch("/api/example", {
        credentials: "include"
    });
}

Frequently Asked Questions