# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdkdocs.deva.me/authentication/session-persistence.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.