Session Persistence

The Deva SDK automatically maintains user sessions across page refreshes using browser storage, eliminating the need for users to re-authenticate on every page load.

How It Works

The SDK uses sessionStorage to persist authentication data:

What's Stored:

  • Access tokens

  • Refresh tokens

  • ID tokens

  • Token expiration times

  • Authentication state

  • PKCE code verifier (temporary, during OAuth flow)

  • Auth in progress flag (tracks ongoing authentication)

Automatic Management:

  • Data saved automatically after login

  • Retrieved automatically on page load

  • Cleared automatically on logout

  • Isolated per tab/window for security

Session Lifecycle

Session Creation

When a user logs in:

  1. OAuth flow completes successfully

  2. Tokens are received from Deva

  3. SDK stores tokens in sessionStorage

  4. User remains authenticated

Learn about retrieving the access token

Session Restoration

When a user refreshes the page:

  1. SDK checks sessionStorage for existing tokens

  2. If valid tokens exist, session is restored

  3. User stays logged in without re-authentication

  4. If tokens expired, automatic refresh occurs

Learn about token refresh

Session Termination

Sessions end when:

  • User explicitly logs out

  • Browser/tab is closed

  • Tokens expire and cannot be refreshed

Storage Mechanism

sessionStorage vs localStorage

The SDK uses sessionStorage (not localStorage):

Feature
sessionStorage (Used)
localStorage

Lifetime

Until browser closed

Indefinite

Scope

Per tab/window

Across all tabs

Security

Cleared on close

Persists forever

Why sessionStorage?

  • Better security - sessions don't persist indefinitely

  • Automatic cleanup when browser closes

  • Prevents token exposure in long-term storage

Cross-Tab Behavior

Tab Isolation:

sessionStorage provides per-tab isolation - each browser tab/window maintains its own independent session:

  • New tabs require new login - Opening a new tab does NOT share the authenticated session

  • No cross-tab synchronization - Sessions are completely isolated between tabs

  • Independent logout - Logging out in one tab does NOT affect other tabs

  • Enhanced security - Prevents session sharing across tab contexts

Browser Behavior:

  • Same tab: Session persists across page refreshes

  • New tab: Requires fresh authentication

  • Duplicate tab (browser feature): May inherit sessionStorage on some browsers

Session Security

Built-in Security:

  • Tokens stored only in sessionStorage

  • No long-term persistence

  • Automatic cleanup on browser close

  • Tokens never exposed to URL or console

Your Responsibility:

  • Use HTTPS in production

  • Don't manually access or modify sessionStorage

  • Let the SDK manage token lifecycle

Learn about security best practices

Handling Session States

The SDK provides status through the useDeva() hook:

const { isReady, isAuthenticated } = useDeva();

if (!isReady) {
  return <Loading />; // SDK checking for existing session
}

if (!isAuthenticated) {
  return <LoginPrompt />; // No active session
}

return <AuthenticatedContent />; // Session active

States:

  • isReady: false - SDK initializing, checking storage

  • isReady: true, isAuthenticated: false - No session found

  • isReady: true, isAuthenticated: true - Active session

Common Scenarios

Page Refresh

Session automatically restored if tokens are valid. No user action needed.

Browser Close/Reopen

Session cleared. User must log in again when reopening the browser.

Token Expiration

SDK automatically refreshes tokens in the background. Session continues seamlessly.

Network Offline

Existing session remains active. New API calls will fail until network restored.

Logout

All stored data cleared immediately. User must log in again.

Developer Notes

Session persistence is automatic - you don't need to:

  • Manually save tokens

  • Check sessionStorage

  • Restore sessions

  • Handle storage events

The SDK manages everything for you.

To check session status:

const { isAuthenticated, isReady } = useDeva();

That's all you need. The SDK handles the rest.

Related Documentation

PreviousToken ManagementNextOverview

Last updated