Skip to main content

Session Management

The session management settings allow you to customize session lifetime and behavior for your Web3Auth integration. These settings determine how long user sessions remain active before requiring re-authentication, providing flexibility to balance security requirements with user experience.

Session Management Settings

Session duration overview​

Session duration controls how long a user's authentication session remains valid before automatic expiration. This setting directly impacts both security posture and user convenience, making it a critical configuration for production applications.

Default configuration​

You may configure the session duration down to the second:

  • Default duration: 1 day (24 hours)
  • Minimum duration: 1 second
  • Maximum duration: 30 days (720 hours)

Configuring session duration​

Setting session lifetime​

  1. Navigate to Project Settings → Advanced → Session Management.
  2. At the Session Duration setting, enter the desired duration in the provided format:
  • Seconds: 1s, 30s, 60s
  • Minutes: 1m, 30m, 60m
  • Hours: 1h, 12h, 24h
  • Days: 1d, 7d, 30d
  1. Save the configuration to apply your changes.

Security considerations​

Short session durations​

Maintaining short sessions supports:

  • Enhanced security: Reduced exposure window if credentials are compromised
  • Compliance: Meets strict security requirements for sensitive applications
  • Risk mitigation: Limits potential damage from unauthorized access
  • Regular validation: Ensures users are actively using the application

The following durations are typical for the stated use cases:

  • High security: 30m-2h
  • Financial apps: 1-4h
  • Admin panels: 2-8h

Long session durations​

In some use cases longer session durations can benefit the user:

  • Improved UX: Reduces authentication friction for users
  • Productivity: Minimizes workflow interruptions
  • Retention: Decreases abandonment due to re-authentication
  • Convenience: Better for applications with frequent usage

The following durations are typical for the stated use cases:

  • Consumer Apps: 7-30d
  • Gaming: 14-30d
  • Content apps: 7-30d

Application-specific recommendations​

Web applications​
Session Duration: 1-7d
Rationale: Balance between security and convenience
Mobile applications​
Session Duration: 14-30d
Rationale: Device-based security with biometric re-authentication
Gaming applications​
Session Duration: 30d
Rationale: Minimal friction for entertainment applications

Advanced session behaviors​

Session renewal​

Web3Auth sessions can be renewed through various mechanisms:

Automatic renewal​

  • Sessions automatically extend on user activity
  • Background refresh maintains active sessions
  • Seamless experience without user intervention

Manual renewal​

  • Explicit user action required for session extension
  • Greater control over session lifecycle
  • Suitable for high-security environments

Session termination​

Sessions may be terminated automatically, or manually.

Automatic termination events​

  • Session duration expiry
  • Extended inactivity periods
  • Security-triggered logout
  • Device/browser changes

Manual termination​

  • User-initiated logout
  • Administrative session termination
  • Forced logout from dashboard

Implementation considerations​

Frontend integration​

Session Status Monitoring:

// Check session status
const isAuthenticated = await web3auth.status

// Handle session expiry
web3auth.on('session_expired', () => {
  // Redirect to login or show re-authentication modal
  handleSessionExpiry()
})

Graceful Session Handling:

// Monitor session state
setInterval(async () => {
  const sessionValid = await web3auth.isLoggedIn()
  if (!sessionValid) {
    // Handle session expiry gracefully
    await handleSessionExpiry()
  }
}, 60000) // Check every minute

Backend validation​

Token Validation:

import jwt from 'jsonwebtoken'

// Validate session token
function validateSession(token) {
  try {
    const decoded = jwt.verify(token, publicKey)
    const now = Math.floor(Date.now() / 1000)

    if (decoded.exp < now) {
      throw new Error('Session expired')
    }

    return decoded
  } catch (error) {
    // Handle session validation failure
    throw new Error('Invalid session')
  }
}

Security best practices​

Session security guidelines​

Token Management:

  • Store session tokens securely (HTTPOnly cookies for web)
  • Implement proper token rotation
  • Use secure transmission (HTTPS only)
  • Clear tokens on logout

Monitoring and Alerting:

  • Track unusual session patterns
  • Monitor concurrent sessions
  • Alert on suspicious activity
  • Log session events for audit

Multi-Device Considerations:

  • Limit concurrent sessions per user
  • Implement device fingerprinting
  • Provide session management UI
  • Enable remote session termination

Compliance requirements​

Industry Standards:

  • PCI DSS: Maximum 15-minute idle timeout for payment systems
  • HIPAA: Regular session timeouts for healthcare data
  • SOX: Documented session management for financial systems
  • GDPR: User control over session data and duration

Risk Assessment Matrix:

Risk LevelMax Session DurationRe-auth Frequency
Critical1-2 hoursEvery action
High2-8 hoursDaily
Medium1-7 daysWeekly
Low7-30 daysMonthly

Troubleshooting session issues​

Common session problems​

Premature Session Expiry:

  • Check system clock synchronization
  • Verify session duration configuration
  • Review token validation logic
  • Check for timezone issues

Sessions Not Expiring:

  • Confirm session duration settings
  • Check automatic renewal behavior
  • Verify backend token validation
  • Review frontend session monitoring

Inconsistent Session Behavior:

  • Check cross-device synchronization
  • Verify token storage mechanisms
  • Review session renewal logic
  • Test different browser/app configurations

Debugging tools​

Session Inspection:

// Debug session information
console.log('Session Duration:', web3auth.sessionDuration)
console.log('Session Start:', web3auth.sessionStartTime)
console.log('Session Expires:', web3auth.sessionExpiryTime)
console.log('Time Remaining:', web3auth.sessionTimeRemaining)

Token Analysis:

// Decode and inspect session token
const jwt = require('jsonwebtoken')
const decoded = jwt.decode(sessionToken, { complete: true })
console.log('Token Header:', decoded.header)
console.log('Token Payload:', decoded.payload)
console.log('Issued At:', new Date(decoded.payload.iat * 1000))
console.log('Expires At:', new Date(decoded.payload.exp * 1000))

Next steps​

On this page