Session Management

Para’s Server SDK enables you to import and manage client-side sessions within your server environment. This allows your server to perform authenticated blockchain operations on behalf of users without requiring them to re-authenticate. The server can also validate existing client sessions using either the Para client or dedicated verification endpoints.

Importing Client Sessions

To use a client session on your server, you need to:

Export the session from the client-side Para instance
Transfer the session to your server securely
Import the session into your server-side Para instance

Client-Side Session Export

First, have your client-side application export the active session:

// Client-side
const para = new Para(Environment.BETA, "YOUR_API_KEY");

// Export the current session
const serializedSession = await para.exportSession();

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

If signing on the server isn’t required, you can pass { excludeSigners: true } as an argument to exportSession to remove the signer data from the exported wallets, enhancing security:

const serializedSession = await para.exportSession({ excludeSigners: true });

Server-Side Session Import

On your server, import the session into a Para Server SDK instance:

import { Para as ParaServer, Environment } from "@getpara/server-sdk";

// Initialize the Para Server SDK
const paraServer = new ParaServer(Environment.BETA, "YOUR_API_KEY");

app.post("/api/import-session", async (req, res) => {
  try {
    // Import the session from the client
    await paraServer.importSession(req.body.session);
    
    // Now you can use the paraServer instance for authenticated operations
    // ...

    res.status(200).json({ success: true });
  } catch (error) {
    res.status(500).json({ error: "Failed to import session" });
  }
});

Create a new Para client instance for each request when handling multiple users. This prevents session conflicts between different users’ requests and ensures security isolation.

Session Validation

You can validate sessions on the server side to ensure they’re still active before performing operations.

Using the Para Client

import { Para as ParaServer, Environment } from "@getpara/server-sdk";

const paraServer = new ParaServer(Environment.BETA, "YOUR_API_KEY");

app.post("/api/authenticated-action", async (req, res) => {
  try {
    // Import the session
    await paraServer.importSession(req.body.session);
    
    // Check if the session is still active
    const isActive = await paraServer.isSessionActive();
    
    if (!isActive) {
      return res.status(401).json({ error: "Session expired" });
    }
    
    // Proceed with authenticated operations
    // ...
    
    res.status(200).json({ success: true });
  } catch (error) {
    res.status(500).json({ error: "Operation failed" });
  }
});

Using Verification Tokens

For non-Node.js servers or scenarios where you only need to validate a session without importing it, Para provides dedicated verification endpoints:

// Client-side: Get a verification token
const verificationToken = await para.getVerificationToken();

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

On your server, verify the token against Para’s API:

// Server-side verification
app.post("/api/verify-session", async (req, res) => {
  const { verificationToken } = req.body;
  
  if (!verificationToken) {
    return res.status(400).json({ error: "Missing verification token" });
  }
  
  // Set the correct URL based on your environment
  const verifyUrl = "https://api.beta.getpara.com/sessions/verify";
  
  try {
    const response = await fetch(verifyUrl, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-external-api-key": "YOUR_API_KEY"
      },
      body: JSON.stringify({ verificationToken }),
    });
    
    if (response.status === 403) {
      return res.status(403).json({ error: "Session expired" });
    }
    
    const userData = await response.json();
    // userData contains { authType, identifier }
    
    // Proceed with authenticated operations
    res.status(200).json({ userData });
  } catch (error) {
    res.status(500).json({ error: "Verification failed" });
  }
});

The verification endpoints are environment-specific:

Environment	Verification URL
SANDBOX	`https://api.sandbox.getpara.com/sessions/verify`
BETA	`https://api.beta.getpara.com/sessions/verify`
PROD	`https://api.getpara.com/sessions/verify`

The verification response will contain the authentication type, identifier, and optionally the OAuth method used:

{
  authType: "email" | "phone" | "farcaster" | "telegram" | "externalWallet";
  identifier: string;
  oAuthMethod?: "google" | "x" | "discord" | "facebook" | "apple";
}