Web Session Management

Guide to managing authentication sessions in Para for web applications

Para provides a comprehensive set of methods for managing authentication sessions in web applications. These sessions are crucial for secure transaction signing and other authenticated operations. Proper session management helps maintain security while ensuring a seamless user experience.

Session Duration

The Para session length is 2 hours by default, but can be configured to up to 30 days. To configure this parameter, please visit the Configuration section of the Developer Portal. A user signing a message or transaction extends the session by the duration of the session length.

Managing Sessions

Checking Session Status

Use isSessionActive() to verify whether a user’s session is currently valid before performing authenticated operations.

async isSessionActive(): Promise<boolean>

This method returns a boolean indicating if the session is currently valid and active. For external wallet connections, this will always return true.

Example usage:

const para = new Para(env, apiKey);

try {
  const isActive = await para.isSessionActive();
  if (!isActive) {
    // Handle expired session
    // See options below for session refresh
  }
} catch (error) {
  console.error("Session check failed:", error);
}

Maintaining Active Sessions

Use keepSessionAlive() to extend an active session’s validity without requiring full reauthentication.

async keepSessionAlive(): Promise<boolean>

This is a lightweight method that attempts to maintain the current session and returns a boolean indicating success or failure.

Example usage:

const para = new Para(env, apiKey);

try {
  const success = await para.keepSessionAlive();
  if (!success) {
    // Handle failed session maintenance
    // Consider initiating a full authentication flow
  }
} catch (error) {
  console.error("Session maintenance failed:", error);
}

If you’re using the React SDK and the ParaProvider component, you can leverage automatic session management:

// The ParaProvider will automatically keep sessions alive by default
<ParaProvider>
  <YourApp />
</ParaProvider>

// To disable automatic session management
<ParaProvider config={paraConfig} disableAutoSessionKeepAlive={true}>
  <YourApp />
</ParaProvider>

When using the ParaProvider component from the React SDK, it automatically keeps sessions alive in the background by calling keepSessionAlive() periodically. You can disable this behavior by setting the disableAutoSessionKeepAlive prop to true if you prefer to manage sessions manually.

Refreshing Expired Sessions

Para provides the refreshSession() method when a session has expired.

async refreshSession({ shouldOpenPopup } = {}): Promise<string>

It’s currently recommended to initiate a full authentication flow rather than using refreshSession() when sessions expire. The refresh flow is being improved in upcoming releases.

For most applications, when a session expires, it’s better to guide users through a complete authentication process:

const para = new Para(env, apiKey);

// When session expires, initiate a full authentication
if (!(await para.isSessionActive())) {
  //route to authentication page
}

Client-Server Session Transfer

Exporting Sessions for Server-Side Operations

Use exportSession() when you need to transfer session state to your server for performing operations on behalf of the user.

exportSession({ excludeSigners?: boolean }): string

Returns a Base64 encoded string containing the session state, including user details, wallet information, and authentication data.

By default, the exported session includes user signers which allow for server-side signing. If you don’t need signing capabilities on your server, use the excludeSigners option to enhance security.

Example client-side export:

const para = new Para(env, apiKey);

// After user authentication
// Full session with signing capabilities
const fullSession = para.exportSession();

// OR

// Session without signing capabilities (recommended if signing not needed)
const secureSession = para.exportSession({ excludeSigners: true });

// Send to your server

To learn more about handling session on the server, check out the following guide:

Server-Side Session Management

Learn how to manage Para sessions on your server.

Sessions with Pre-Generated Wallets

When using pre-generated wallets, session management works differently as these wallets don’t require traditional authentication.

For pre-generated wallets, the session is considered always active as long as the UserShare is loaded in the Para client instance. Traditional session expiration doesn’t apply in this scenario.

const para = new Para(env, apiKey);

// Set a pre-generated wallet
await para.setUserShare(userShare);

// Session checks will return true as long as userShare is loaded
const isActive = await para.isSessionActive(); // Always true for pre-gen wallets

Pre-Generated Wallets

Learn more about pregenerated wallets.

Best Practices

1. Proactive Session Management: Check session status before operations that require authentication.

2. Regular Session Extension: For long user sessions, periodically call keepSessionAlive() or use the ParaProvider automatic session management.

3. Security-First Approach: When exporting sessions to servers, use excludeSigners: true unless server-side signing is explicitly needed.

4. Graceful Expiration Handling: Provide a smooth re-authentication flow when sessions expire.

5. Session Verification: For security-critical operations, verify sessions on both client and server sides.