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@alpha";

// 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@alpha";

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 JWT Authentication

Once a user is signed in, you can request a Para JWT token. This token will provide attestations for the user’s ID, their identity, and any wallets they have provisioned via your application.

To request a token, use the issueJwt method. The method returns the token itself as well as the JWKS key ID (kid) for the keypair that signed it.

const paraServer  = new ParaServer(Environment.BETA, 'your-api-key');

const { token, keyId } = await paraServer.issueJwt();

Depending on the user in question, a decoded token payload might resemble the following:

{
  "data": {
    "userId": "d5358219-38d3-4650-91a8-e338131d1c5e",
    "wallets": [
      {
        "id": "de4034f1-6b0f-4a98-87a5-e459db4d3a03",
        "type": "EVM",
        "address": "0x9dd3824f045c77bc369485e8f1dd6b452b6be617",
        "publicKey": "0x0465434f76c8321f386856c44e735fd365a09d42c1da03489184b651c2052ea1c7b19c54722ed828458c1d271cc590b0818d8c7df423f71e92683f9e819095a8c6"
      },
      {
        "id": "d70f64e4-266a-457e-9cea-eeb42341a975",
        "type": "SOLANA",
        "address": "EEp7DbBu5yvgf7Pr9W17cATPjCqUxY8K8R3dFbg53a3W",
        "publicKey": ""
      }
    ],
    "email": "email@example.com",
    "authType": "email",
    "identifier": "email@example.com",
    "oAuthMethod": "google" // or: undefined | "x" | "discord" | "facebook" | "apple"
  },
  "iat": 1745877709,
  "exp": 1745879509,
  "sub": "d5358219-38d3-4650-91a8-e338131d1c5e"
}

Para’s JSON Web Keys Set (JWKS) file(s) are available at the following URLs:

​

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_SECRET_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, identifier, and optionally the OAuth method used:

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

​

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.

​

Verifying Wallet Ownership

To verify that a wallet address matches one of your users’ embedded wallets, you can send a request to one of the following endpoints:

Pass the address for the wallet in the POST request body:

// Server-side verification
app.post("/api/verify-wallet", async (req, res) => {
  const { address } = req.body;
  
  if (!address) {
    return res.status(400).json({ error: "Missing address" });
  }
  
  // Set the correct URL based on your environment
  const verifyUrl = "https://api.beta.getpara.com/wallets/verify";
  
  try {
    const response = await fetch(verifyUrl, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-external-api-key": "YOUR_SECRET_API_KEY"
      },
      body: JSON.stringify({ address }),
    });
    
    // No matching wallet found
    if (response.status === 404) {
      return res.status(404).json({ error: `Wallet not found with address: ${address}` });
    }
    
    const { walletId } = await response.json();
    
    // Return the matched wallet ID:
    res.status(200).json({ walletId });
  } catch (error) {
    res.status(500).json({ error: "Verification failed" });
  }
});

​

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.