> For the complete documentation index, see [llms.txt](https://sdkdocs.deva.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdkdocs.deva.me/authentication/session-persistence.md).

# 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](/authentication/token-management.md#retrieve-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](/authentication/token-management.md#token-refresh-flow)

### 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](/authentication/oauth-integration.md#security-best-practices)

***

## Handling Session States

The SDK provides status through the `useDeva()` hook:

```tsx
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:**

```tsx
const { isAuthenticated, isReady } = useDeva();
```

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

***

## Related Documentation

* [Authentication Flow](/core-concepts/authentication-flow.md) - How authentication works
* [Token Management](/authentication/token-management.md) - Token lifecycle and refresh
* [Login Implementation](/authentication/login-implementation.md) - Implement login functionality
* [Logout Handling](/authentication/logout-handling.md) - Implement logout functionality
* [Provider Pattern](/core-concepts/provider-pattern.md) - Managing auth state