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("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 } from "@getpara/server-sdk@alpha";

// Initialize the Para Server SDK
const paraServer = new ParaServer("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 } from "@getpara/server-sdk@alpha";

const paraServer = new ParaServer("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('your-api-key');

const { token, keyId } = await paraServer.issueJwt();
The token’s expiry will be determined by your customized session length, or else will default to 30 minutes. Issuing a token, like most authenticated API operations, will also renew and extend the session for that duration.
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:
EnvironmentJWKS URL
SANDBOXhttps://api.sandbox.getpara.com/.well-known/jwks.json
BETAhttps://api.beta.getpara.com/.well-known/jwks.json
PRODhttps://api.getpara.com/.well-known/jwks.json

​
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.
Use your Secret API Key from the Developer Portal to authenticate requests to the verification endpoints. This key is different from the public-facing API Key used in the Para client.
// 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:
EnvironmentVerification URL
SANDBOXhttps://api.sandbox.getpara.com/sessions/verify
BETAhttps://api.beta.getpara.com/sessions/verify
PRODhttps://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";
}

​
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);
}
You can configure session duration (up to 30 days) in the . This affects how long sessions remain valid without explicit extension.

​
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:
EnvironmentURL
SANDBOXhttps://api.sandbox.getpara.com/wallets/verify
BETAhttps://api.beta.getpara.com/wallets/verify
PRODhttps://api.getpara.com/wallets/verify
Use your Secret API Key from the Developer Portal to authenticate requests to this endpoint. This key is different from the public-facing API Key used in the Para client.
Pass the address for the wallet in the POST request body:
Node.js
// 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:

Web Session Management

​
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.

Session Import Example