Manage user sessions

User sessions determine how long users stay signed in to your application. After users successfully authenticate, you receive session tokens that manage their access. These tokens control session duration, multi-device access, and cross-product authentication within your company’s ecosystem.

Scalekit provides session management capabilities out of the box. Your application receives an access_token and refresh_token in the authentication response. This guide shows you how to store these tokens securely and refresh them before they expire.

Store session tokens securely

After successful user authentication, your application receives session tokens in the response object.

1
const authResult = await scalekit.authenticateWithCode(
2
  code, redirectUri
3
);
4

5
// authResult contains user profile and session tokens
6
const { user, accessToken, refreshToken, expiresIn } = authResult;

1
auth_result = scalekit_client.authenticate_with_code(
2
  code=code,
3
  redirect_uri=redirect_uri
4
)
5

6
# auth_result contains user profile and session tokens
7
user = auth_result.user
8
access_token = auth_result.access_token
9
refresh_token = auth_result.refresh_token
10
expires_in = auth_result.expires_in

1
authResult, err := scalekitClient.AuthenticateWithCode(
2
  code,
3
  redirectUri,
4
)
5
if err != nil {
6
  // Handle error
7
}
8

9
// authResult contains user profile and session tokens
10
user := authResult.User
11
accessToken := authResult.AccessToken
12
refreshToken := authResult.RefreshToken
13
expiresIn := authResult.ExpiresIn

1
AuthResult authResult = scalekitClient.authentication().authenticateWithCode(
2
  code,
3
  redirectUri
4
);
5

6
// authResult contains user profile and session tokens
7
User user = authResult.getUser();
8
String accessToken = authResult.getAccessToken();
9
String refreshToken = authResult.getRefreshToken();
10
int expiresIn = authResult.getExpiresIn();

Store each token based on its security requirements:

Access Token: Store in a secure, HTTP-only cookie to prevent XSS attacks. This token has a short lifespan and provides access to protected resources.
Refresh Token: Store in your backend database or secure server-side storage. This long-lived token generates new access tokens.

Here’s how to set secure cookies:

1
import cookieParser from 'cookie-parser';
2

3
// Configure cookie parser middleware
4
app.use(cookieParser());
5

6
// After receiving the authResult from scalekit.authenticateWithCode()
7
const { accessToken, expiresIn, refreshToken, user } = authResult;
8

9
// Store the refresh token in your database
10
await db.saveRefreshToken(user.id, refreshToken);
11

12
// Set the access token as a secure cookie
13
res.cookie('accessToken', accessToken, {
14
  maxAge: (expiresIn - 60) * 1000, // Convert to milliseconds, subtract 60s buffer
15
  httpOnly: true,
16
  secure: process.env.NODE_ENV === 'production',
17
  sameSite: 'strict'
18
});

1
from flask import Flask, make_response
2
import os
3

4
app = Flask(__name__)
5

6
# After receiving the auth_result from scalekit.authenticate_with_code()
7
access_token = auth_result.access_token
8
expires_in = auth_result.expires_in
9
refresh_token = auth_result.refresh_token
10
user = auth_result.user
11

12
# Store the refresh token in your database
13
db.save_refresh_token(user.id, refresh_token)
14

15
# Set the access token as a secure cookie
16
response = make_response()
17
response.set_cookie(
18
  'accessToken',
19
  access_token,
20
  max_age=(expires_in - 60) * 1000,  # Convert to milliseconds, subtract 60s buffer
21
  httponly=True,
22
  secure=os.environ.get('FLASK_ENV') == 'production',
23
  samesite='Strict'
24
)

1
import (
2
  "net/http"
3
  "os"
4
  "time"
5
  "github.com/gin-gonic/gin"
6
)
7

8
// After receiving the authResult from scalekit.AuthenticateWithCode()
9
accessToken := authResult.AccessToken
10
expiresIn := authResult.ExpiresIn
11
refreshToken := authResult.RefreshToken
12
user := authResult.User
13

14
// Store the refresh token in your database
15
db.SaveRefreshToken(user.ID, refreshToken)
16

17
// Set the access token as a secure cookie
18
c.SetCookie(
19
  "accessToken",
20
  accessToken,
21
  (expiresIn-60)*1000, // Convert to milliseconds, subtract 60s buffer
22
  "/",
23
  "",
24
  os.Getenv("GIN_MODE") == "release",
25
  true, // httpOnly
26
)
27
c.SetSameSite(http.SameSiteStrictMode)

1
import javax.servlet.http.Cookie;
2
import javax.servlet.http.HttpServletResponse;
3
import org.springframework.core.env.Environment;
4

5
@Autowired
6
private Environment env;
7

8
// After receiving the authResult from scalekit.authenticateWithCode()
9
String accessToken = authResult.getAccessToken();
10
int expiresIn = authResult.getExpiresIn();
11
String refreshToken = authResult.getRefreshToken();
12
User user = authResult.getUser();
13

14
// Store the refresh token in your database
15
db.saveRefreshToken(user.getId(), refreshToken);
16

17
// Set the access token as a secure cookie
18
Cookie cookie = new Cookie("accessToken", accessToken);
19
cookie.setMaxAge((expiresIn - 60) * 1000); // Convert to milliseconds, subtract 60s buffer
20
cookie.setHttpOnly(true);
21
cookie.setSecure("production".equals(env.getActiveProfiles()[0]));
22
cookie.setPath("/");
23
response.addCookie(cookie);

Configure session settings from your Scalekit dashboard’s Session Configuration to control session lifetimes and security policies.

Verify the access token

Create middleware to protect your application routes. This middleware validates the access token on every request to secured endpoints.

1
async function verifyToken(req, res, next) {
2
  const { accessToken } = req.cookies;
3

4
  if (!accessToken) {
5
    return res.status(401).json({ error: 'Authentication required' });
6
  }
7

8
  try {
9
    // Validate the token using Scalekit SDK
10
    const { user } = await scalekit.validateAccessToken(accessToken);
11
    req.user = user; // Attach user information to the request
12
    next();
13
  } catch (error) {
14
    // Token is expired or invalid - attempt to refresh
15
    return handleTokenRefresh(req, res, next);
16
  }
17
}

1
from flask import request, jsonify
2
from functools import wraps
3

4
def verify_token(f):
5
    @wraps(f)
6
    def decorated_function(*args, **kwargs):
7
        access_token = request.cookies.get('accessToken')
8

9
        if not access_token:
10
            return jsonify({'error': 'Authentication required'}), 401
11

12
        try:
13
            # Validate the token using Scalekit SDK
14
            user = scalekit.validate_access_token(access_token)
15
            request.user = user  # Attach user information to the request
16
            return f(*args, **kwargs)
17
        except Exception:
18
            # Token is expired or invalid - attempt to refresh
19
            return handle_token_refresh(f, *args, **kwargs)
20

21
    return decorated_function

1
import (
2
  "net/http"
3
  "github.com/gin-gonic/gin"
4
)
5

6
func VerifyToken() gin.HandlerFunc {
7
  return func(c *gin.Context) {
8
    accessToken, err := c.Cookie("accessToken")
9

10
    if err != nil || accessToken == "" {
11
      c.JSON(http.StatusUnauthorized, gin.H{"error": "Authentication required"})
12
      c.Abort()
13
      return
14
    }
15

16
    // Validate the token using Scalekit SDK
17
    user, err := scalekit.ValidateAccessToken(accessToken)
18
    if err != nil {
19
      // Token is expired or invalid - attempt to refresh
20
      handleTokenRefresh(c)
21
      return
22
    }
23

24
    c.Set("user", user) // Attach user information to the context
25
    c.Next()
26
  }
27
}

1
import javax.servlet.http.HttpServletRequest;
2
import javax.servlet.http.HttpServletResponse;
3
import javax.servlet.http.Cookie;
4
import org.springframework.web.servlet.HandlerInterceptor;
5

6
@Component
7
public class AuthInterceptor implements HandlerInterceptor {
8
  @Override
9
  public boolean preHandle(
10
    HttpServletRequest request,
11
    HttpServletResponse response,
12
    Object handler
13
  ) throws Exception {
14
    String accessToken = getCookieValue(request, "accessToken");
15

16
    if (accessToken == null) {
17
      response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
18
      response.getWriter().write("{\"error\": \"Authentication required\"}");
19
      return false;
20
    }
21

22
    try {
23
      // Validate the token using Scalekit SDK
24
      User user = scalekit.validateAccessToken(accessToken);
25
      request.setAttribute("user", user); // Attach user information to the request
26
      return true;
27
    } catch (Exception e) {
28
      // Token is expired or invalid - attempt to refresh
29
      return handleTokenRefresh(request, response);
30
    }
31
  }
32

33
  private String getCookieValue(HttpServletRequest request, String cookieName) {
34
    Cookie[] cookies = request.getCookies();
35
    if (cookies != null) {
36
      for (Cookie cookie : cookies) {
37
        if (cookieName.equals(cookie.getName())) {
38
          return cookie.getValue();
39
        }
40
      }
41
    }
42
    return null;
43
  }
44
}

Refresh expired access tokens

When access tokens expire, use the refresh token to get new ones. This maintains user sessions without requiring re-authentication.

1
async function handleTokenRefresh(req, res, next) {
2
  // Get the user ID from the expired token or session storage
3
  const userId = req.session?.userId || req.user?.id;
4

5
  if (!userId) {
6
    return res.status(401).json({ error: 'Authentication required' });
7
  }
8

9
  // Retrieve the stored refresh token from your database
10
  const storedRefreshToken = await db.getRefreshToken(userId);
11

12
  if (!storedRefreshToken) {
13
    return res.status(401).json({ error: 'Session expired' });
14
  }
15

16
  try {
17
    // Get new tokens using the refresh token
18
    const authResult = await scalekit.refreshToken(storedRefreshToken);
19
    const { accessToken, expiresIn, refreshToken: newRefreshToken } = authResult;
20

21
    // Update the stored refresh token
22
    await db.saveRefreshToken(userId, newRefreshToken);
23

24
    // Set the new access token as a cookie
25
    res.cookie('accessToken', accessToken, {
26
      maxAge: (expiresIn - 60) * 1000,
27
      httpOnly: true,
28
      secure: process.env.NODE_ENV === 'production',
29
      sameSite: 'strict'
30
    });
31

32
    // Attach user information and continue
33
    req.user = authResult.user;
34
    next();
35

36
  } catch (error) {
37
    // Refresh failed - user must sign in again
38
    res.clearCookie('accessToken');
39
    return res.status(401).json({ error: 'Session expired. Please sign in again.' });
40
  }
41
}

1
from flask import request, jsonify, make_response
2

3
def handle_token_refresh(f, *args, **kwargs):
4
    # Get the user ID from the expired token or session storage
5
    user_id = request.session.get('userId') if hasattr(request, 'session') else getattr(request, 'user', {}).get('id')
6

7
    if not user_id:
8
        return jsonify({'error': 'Authentication required'}), 401
9

10
    # Retrieve the stored refresh token from your database
11
    stored_refresh_token = db.get_refresh_token(user_id)
12

13
    if not stored_refresh_token:
14
        return jsonify({'error': 'Session expired'}), 401
15

16
    try:
17
        # Get new tokens using the refresh token
18
        auth_result = scalekit.refresh_token(stored_refresh_token)
19
        access_token = auth_result.access_token
20
        expires_in = auth_result.expires_in
21
        new_refresh_token = auth_result.refresh_token
22

23
        # Update the stored refresh token
24
        db.save_refresh_token(user_id, new_refresh_token)
25

26
        # Set the new access token as a cookie
27
        response = make_response(f(*args, **kwargs))
28
        response.set_cookie(
29
            'accessToken',
30
            access_token,
31
            max_age=(expires_in - 60) * 1000,
32
            httponly=True,
33
            secure=os.environ.get('FLASK_ENV') == 'production',
34
            samesite='Strict'
35
        )
36

37
        # Attach user information and continue
38
        request.user = auth_result.user
39
        return response
40

41
    except Exception:
42
        # Refresh failed - user must sign in again
43
        response = make_response(jsonify({'error': 'Session expired. Please sign in again.'}), 401)
44
        response.set_cookie('accessToken', '', expires=0)
45
        return response

1
import (
2
  "net/http"
3
  "github.com/gin-gonic/gin"
4
)
5

6
func handleTokenRefresh(c *gin.Context) {
7
  // Get the user ID from the expired token or session storage
8
  userID := getUserIDFromContext(c) // Helper function to get user ID
9

10
  if userID == "" {
11
    c.JSON(http.StatusUnauthorized, gin.H{"error": "Authentication required"})
12
    c.Abort()
13
    return
14
  }
15

16
  // Retrieve the stored refresh token from your database
17
  storedRefreshToken, err := db.GetRefreshToken(userID)
18

19
  if err != nil || storedRefreshToken == "" {
20
    c.JSON(http.StatusUnauthorized, gin.H{"error": "Session expired"})
21
    c.Abort()
22
    return
23
  }
24

25
  // Get new tokens using the refresh token
26
  authResult, err := scalekit.RefreshToken(storedRefreshToken)
27
  if err != nil {
28
    // Refresh failed - user must sign in again
29
    c.SetCookie("accessToken", "", -1, "/", "", false, true)
30
    c.JSON(http.StatusUnauthorized, gin.H{"error": "Session expired. Please sign in again."})
31
    c.Abort()
32
    return
33
  }
34

35
  // Update the stored refresh token
36
  db.SaveRefreshToken(userID, authResult.RefreshToken)
37

38
  // Set the new access token as a cookie
39
  c.SetCookie(
40
    "accessToken",
41
    authResult.AccessToken,
42
    (authResult.ExpiresIn-60)*1000,
43
    "/",
44
    "",
45
    os.Getenv("GIN_MODE") == "release",
46
    true,
47
  )
48

49
  // Attach user information and continue
50
  c.Set("user", authResult.User)
51
  c.Next()
52
}

1
import javax.servlet.http.HttpServletRequest;
2
import javax.servlet.http.HttpServletResponse;
3
import javax.servlet.http.Cookie;
4

5
private boolean handleTokenRefresh(HttpServletRequest request, HttpServletResponse response)
6
    throws Exception {
7
  // Get the user ID from the expired token or session storage
8
  String userId = getUserIdFromRequest(request); // Helper method to get user ID
9

10
  if (userId == null) {
11
    response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
12
    response.getWriter().write("{\"error\": \"Authentication required\"}");
13
    return false;
14
  }
15

16
  // Retrieve the stored refresh token from your database
17
  String storedRefreshToken = db.getRefreshToken(userId);
18

19
  if (storedRefreshToken == null) {
20
    response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
21
    response.getWriter().write("{\"error\": \"Session expired\"}");
22
    return false;
23
  }
24

25
  try {
26
    // Get new tokens using the refresh token
27
    AuthResult authResult = scalekit.refreshToken(storedRefreshToken);
28
    String accessToken = authResult.getAccessToken();
29
    int expiresIn = authResult.getExpiresIn();
30
    String newRefreshToken = authResult.getRefreshToken();
31

32
    // Update the stored refresh token
33
    db.saveRefreshToken(userId, newRefreshToken);
34

35
    // Set the new access token as a cookie
36
    Cookie cookie = new Cookie("accessToken", accessToken);
37
    cookie.setMaxAge((expiresIn - 60) * 1000);
38
    cookie.setHttpOnly(true);
39
    cookie.setSecure("production".equals(env.getActiveProfiles()[0]));
40
    cookie.setPath("/");
41
    response.addCookie(cookie);
42

43
    // Attach user information and continue
44
    request.setAttribute("user", authResult.getUser());
45
    return true;
46

47
  } catch (Exception e) {
48
    // Refresh failed - user must sign in again
49
    Cookie expiredCookie = new Cookie("accessToken", "");
50
    expiredCookie.setMaxAge(0);
51
    response.addCookie(expiredCookie);
52
    response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
53
    response.getWriter().write("{\"error\": \"Session expired. Please sign in again.\"}");
54
    return false;
55
  }
56
}

Apply this middleware to protected routes:

1
// Protect routes that require authentication
2
app.get('/dashboard', verifyToken, (req, res) => {
3
  res.json({ message: `Welcome ${req.user.name}!` });
4
});
5

6
app.get('/api/profile', verifyToken, (req, res) => {
7
  res.json({ user: req.user });
8
});

1
# Protect routes that require authentication
2
@app.route('/dashboard')
3
@verify_token
4
def dashboard():
5
    return jsonify({'message': f'Welcome {request.user.name}!'})
6

7
@app.route('/api/profile')
8
@verify_token
9
def profile():
10
    return jsonify({'user': request.user})

1
// Protect routes that require authentication
2
r.GET("/dashboard", VerifyToken(), func(c *gin.Context) {
3
  user, _ := c.Get("user")
4
  c.JSON(http.StatusOK, gin.H{
5
    "message": fmt.Sprintf("Welcome %s!", user.Name),
6
  })
7
})
8

9
r.GET("/api/profile", VerifyToken(), func(c *gin.Context) {
10
  user, _ := c.Get("user")
11
  c.JSON(http.StatusOK, gin.H{"user": user})
12
})

1
// Protect routes that require authentication
2
@GetMapping("/dashboard")
3
public ResponseEntity<Map<String, String>> dashboard(HttpServletRequest request) {
4
  User user = (User) request.getAttribute("user");
5
  Map<String, String> response = new HashMap<>();
6
  response.put("message", "Welcome " + user.getName() + "!");
7
  return ResponseEntity.ok(response);
8
}
9

10
@GetMapping("/api/profile")
11
public ResponseEntity<Map<String, Object>> profile(HttpServletRequest request) {
12
  User user = (User) request.getAttribute("user");
13
  Map<String, Object> response = new HashMap<>();
14
  response.put("user", user);
15
  return ResponseEntity.ok(response);
16
}

Configure session settings

Control user session behavior from your Scalekit dashboard without changing your application code.

Session Settings Dashboard

You can control how long users stay signed in and how often they need to log in again. In your Scalekit dashboard, the Session settings page lets you set these options:

Absolute session timeout: This is the maximum time a user can stay signed in, no matter what. After this time, they must log in again. For example, if you set it to 30 minutes, users will be logged out after 30 minutes, even if they are still using your app.
Idle session timeout: This is the time your app waits before logging out a user who is not active. If you turn this on, the session will end if the user does nothing for the set time. For example, if you set it to 10 minutes, and the user does not click or type for 10 minutes, they will be logged out.
Access token lifetime: This is how long an access token is valid. When it expires, your app needs to get a new token (using the refresh token) so the user can keep using the app without logging in again. For example, if you set it to 5 minutes, your app will need to refresh the token every 5 minutes.

Shorter timeouts provide better security, while longer timeouts reduce authentication interruptions.

What’s next?

Learn how to implement secure user logout to properly end user sessions.
Explore session configuration options to customize security policies.
Set up organization-level authentication policies for enterprise customers.