​
Overview

Para provides a comprehensive set of methods for managing authentication sessions. 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.

​
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
    await para.refreshSession({ shouldOpenPopup: true });
  }
} 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
    await para.refreshSession({ shouldOpenPopup: true });
  }
} catch (error) {
  console.error("Session maintenance failed:", error);
}

​
Refreshing Expired Sessions

Use refreshSession() when a session has fully expired and needs to be reestablished through user authentication.

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

When shouldOpenPopup is true, this method automatically opens an authentication window. Otherwise, it returns a URL that should be opened in a popup for user authentication. After calling refreshSession(), you must use waitForLoginAndSetup() to wait for the authentication to complete.

async waitForLoginAndSetup({ popupWindow, skipSessionRefresh }): Promise<{
  isComplete: boolean;
  isError?: boolean;
  needsWallet?: boolean;
  partnerId?: string;
}>

Pass the popup window reference to waitForLoginAndSetup() when handling popups manually. This enables automatic error detection if the user closes the popup.

Example usage:

const para = new Para(env, apiKey);

// Automatic popup handling
try {
  await para.refreshSession({ shouldOpenPopup: true });
  // Wait for authentication to complete
  const { isComplete, isError } = await para.waitForLoginAndSetup({ skipSessionRefresh: false });
  if (!isComplete || isError) {
    throw new Error("Session refresh failed");
  }
} catch (error) {
  console.error("Session refresh failed:", error);
}

// Manual popup handling
try {
  const authUrl = await para.refreshSession({ shouldOpenPopup: false });
  const popup = window.open(authUrl, "Auth", "width=400,height=600");
  // Wait for authentication to complete
  const { isComplete, isError } = await para.waitForLoginAndSetup({ popupWindow: popup });
  if (!isComplete || isError) {
    throw new Error("Session refresh failed");
  }
} catch (error) {
  console.error("Failed to refresh session:", error);
}

​
Client-Server Session Transfer

​
Exporting Sessions

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

exportSession(): string

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

Example client-side export:

const para = new Para(env, apiKey);

// After user authentication
const serializedSession = para.exportSession();

// Send to server
await fetch("/api/store-session", {
  method: "POST",
  body: JSON.stringify({ session: serializedSession }),
  headers: { "Content-Type": "application/json" },
});

​
Importing Sessions

Use importSession() on your server to restore a previously exported session state.

async importSession(serializedInstanceBase64: string): Promise<void>
Takes a Base64 encoded session string from exportSession() and restores the complete session state.

Example server-side implementation:

const para = new Para(env, apiKey);

app.post("/api/server-action", async (req, res) => {
  try {
    await para.importSession(req.body.session);

    const isActive = await para.isSessionActive();
    if (!isActive) {
      return res.status(401).json({ error: "Session expired" });
    }

    // Perform authenticated operations
    const walletId = para.currentWalletIdsArray[0]?.[0];
    const signature = await para.signMessage({ 
      walletId, 
      messageBase64: messageToSign 
    });

    res.json({ signature });
  } catch (error) {
    res.status(500).json({ error: "Server operation failed" });
  }
});

​
Session Verification Tokens

Alternatively, if your server does not use Node.js, you can request a verification token that can be passed to our servers to validate whether the connected session is valid and fetch related user authentication data - for example, the user’s email address.

Our session verification endpoints are as follows:

EnvironmentURL
SANDBOXhttps://api.sandbox.getpara.com/session/verify
BETAhttps://api.beta.getpara.com/session/verify
PRODhttps://api.getpara.com/session/verify

Send a POST request to one of the above URLs with the header x-partner-id set to your Para API key and the following JSON body:

{
  "verificationToken": "your-verification-token"
}

If the session is no longer valid, the request will return a 403 status code. Otherwise, it will return a JSON object of the form:

{
  authType: "email" | "phone" | "farcaster" | "telegram" | "externalWallet";
  identifier: string;
}

A sample usage:

async function validateSession() {
  const sessionLookupId: string = await para.getVerificationToken();

  const response = await fetch("https://your-domain.com/api/verify-token", {
    method: "POST",
    data: {
      verificationToken,
    }
    headers: {
      "content-type": "application/json",
    },
  });
}