Skip to main content

​
Overview

Session management endpoints help you validate user sessions, refresh expired tokens, and maintain authentication state across your application. Proper session management is critical for security and user experience.

​
Validate Access Tokens

Access tokens should be validated on every API request to ensure they are still valid and have not been revoked.

​
Token Validation Steps

  1. Verify Token Signature: Validate the JWT signature using Scalekit’s public keys
  2. Check Expiration: Ensure the token has not expired (exp claim)
  3. Verify Issuer: Confirm the token was issued by Scalekit (iss claim)
  4. Verify Audience: Ensure the token is intended for your application (aud claim)
  5. Check Claims: Validate required claims are present and valid

​
Validation Examples

    ​
    Refresh Tokens

    When access tokens expire, use refresh tokens to obtain new access tokens without requiring the user to log in again.

    ​
    Refresh Token Endpoint

    ​
    method
    string
    default:"POST"
    POST
    ​
    url
    string
    {SCALEKIT_ENVIRONMENT_URL}/oauth/token

    ​
    Request Parameters

    ​
    grant_type
    string
    required
    Use refresh_token for token refresh flow.
    ​
    refresh_token
    string
    required
    The refresh token received during initial authentication.
    ​
    client_id
    string
    required
    Your Scalekit application client ID.
    ​
    client_secret
    string
    required
    Your Scalekit application client secret.

    ​
    Refresh Token Examples

      ​
      Session Storage

      Store session data securely to maintain user authentication state: 
      // Store session data server-side (recommended)
import session from 'express-session'
import RedisStore from 'connect-redis'
import { createClient } from 'redis'

const redisClient = createClient()
await redisClient.connect()

app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: true, // HTTPS only
    httpOnly: true, // Prevent XSS
    maxAge: 24 * 60 * 60 * 1000, // 24 hours
    sameSite: 'strict' // CSRF protection
  }
}))

// Store tokens in session
app.post('/auth/callback', async (req, res) => {
  const { code } = req.query
  const tokens = await scalekit.authenticateWithCode(code, redirectUri)
  
  // Security: Store tokens in secure session
  req.session.accessToken = tokens.accessToken
  req.session.refreshToken = tokens.refreshToken
  req.session.user = tokens.user
  
  res.redirect('/dashboard')
})

      ​
      Client-Side Sessions (Use with Caution)

      Security Warning: Only store session data client-side if server-side storage is not feasible. Use secure, httpOnly cookies and never expose refresh tokens to client-side JavaScript.
      // If you must store tokens client-side, use secure cookies
import { serialize } from 'cookie'

res.setHeader('Set-Cookie', [
  serialize('access_token', tokens.accessToken, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 3600,
    path: '/'
  }),
  // NEVER expose refresh token to client-side JavaScript
  serialize('refresh_token', tokens.refreshToken, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 30 * 24 * 60 * 60, // 30 days
    path: '/auth/refresh' // Restrict to refresh endpoint only
  })
])

      ​
      Session Security Best Practices

      Critical Security Practices:
      1. Token Storage: Store access tokens and refresh tokens securely. Never expose them in URLs, localStorage, or sessionStorage.
      2. HTTPS Only: Always use HTTPS in production. Session cookies must have the secure flag set.
      3. HttpOnly Cookies: Use httpOnly cookies to prevent XSS attacks from stealing tokens.
      4. CSRF Protection: Use SameSite cookie attribute and CSRF tokens for form submissions.
      5. Token Rotation: Implement refresh token rotation - issue a new refresh token each time an access token is refreshed.
      6. Session Expiration: Set appropriate session timeouts. Balance security with user experience.
      7. Logout Handling: Properly invalidate sessions on logout, including server-side session cleanup.

      ​
      Next Steps

      Logout

      Implement secure logout functionality

      Rate Limits

      Understand API rate limiting

      Build docs developers (and LLMs) love

      Get started for freeTalk to us