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:

1. Export the session from the client-side Para instance
2. Transfer the session to your server securely
3. 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 }),
});

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" });
  }
});

​

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-partner-id": "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:

The verification response will contain the authentication type and identifier:

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

​

Session Management

​

Maintaining Session Validity

To extend the validity of an imported session, you can use the keepSessionAlive method:

try {
  const success = await paraServer.keepSessionAlive();
  if (!success) {
    // Session couldn't be extended
    // The client may need to re-authenticate
  }
} catch (error) {
  console.error("Failed to maintain session:", error);
}

​

Best Practices

1. Create new Para instances per request: Initialize a fresh Para Server SDK instance for each request to prevent session conflicts between users.

2. Secure session transport: Always use HTTPS and consider additional encryption when transferring sessions between client and server.

3. Exclude signers when possible: Use { excludeSigners: true } when exporting sessions if server-side signing isn’t needed.

4. Validate before operations: Always check if a session is active before performing blockchain operations.

5. Handle expiration gracefully: Implement proper error handling for expired sessions, guiding users to re-authenticate when necessary.

6. Consider session verification tokens: For simple authentication checks without full session import, use verification tokens.

7. Set appropriate session duration: Configure session length in the developer portal based on your security requirements.

​

Learn More

For more information about client-side session management and authentication, refer to our web documentation:

​

Examples

To learn more about using sessions on the server, check out this example. Each example route will have both pregen and session based routes for you to test with.