Sessions

A Client Session Token (CST) is a short-lived authentication token scoped to a single client. Use CSTs when you want to give a frontend or mobile client temporary access without exposing the permanent clientApiKey.

Create a Session

Call createClientSession() from your backend whenever a user authenticates:

const session = await wallets.custodian.createClientSession({
  path: { clientId: "cli_..." },
  body: { isAccountAbstracted: false },
});

// session.clientSessionToken — send this to the client
// session.id                 — session ID

Send the clientSessionToken to your frontend. It authenticates the user against Portal for the duration of its validity.

Use a Session Token

Pass the clientSessionToken to initClient() instead of the clientApiKey:

// On the frontend (or a short-lived server-side context):
const client = wallets.initClient({
  token: sessionToken,  // clientSessionToken from your backend
});

const shares = await client.generateWallet();

Session vs clientApiKey

Pattern: Backend Issues Tokens

The typical flow:

User logs in → your backend calls createClientSession()
                              → returns clientSessionToken
                                              → frontend receives token
                                              → frontend calls wallet operations

Your backend never exposes the clientApiKey to the client. It only issues short-lived CSTs.

// Backend endpoint
app.post("/session", requireAuth, async (req, res) => {
  const session = await wallets.custodian.createClientSession({
    path: { clientId: req.user.portalClientId },
    body: {},
  });
  res.json({ token: session.clientSessionToken });
});

// Frontend
const { token } = await fetch("/session").then(r => r.json());
const client = wallets.initClient({ token });