Skip to main content

​
Portal Sessions

The SDK gives you four methods for managing customer portal links. These are the one-time URLs your customers click to see their own billing. This page covers:
  1. Creating a portal session
  2. Getting one portal session
  3. Listing portal sessions
  4. Revoking a portal session
If you’re new to portal sessions, start with the Portal Sessions API reference for a plain-English explanation of what they are and why you’d use them.

​
Setup

import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);
All four portal-sessions methods require a secret key (mf_sk_...). The SDK throws an AuthenticationError immediately if you initialize the client with a publishable key.

​
portalSessions.create

Mints a one-time portal link for a customer. The returned url is what you send to your customer.

​
Signature

await mf.portalSessions.create(params: CreatePortalSessionParams): Promise<PortalSession>

​
Example

const session = await mf.portalSessions.create({
  customerExternalId: "acme-001",
  returnUrl: "https://your-app.com/billing",
});

console.log(session.url);
// → https://portal.marginfront.com/r/mgl_a1b2c3...

// Send this URL to your customer (email, SMS, button in your app, etc.).
Pass either customerExternalId (your system’s ID) or customerId (MarginFront’s UUID). returnUrl is optional and informational. See the Portal Sessions API reference for the full field list and error codes.

​
portalSessions.get

Looks up one portal session by ID. Useful for checking whether a link has been opened or has expired.

​
Signature

await mf.portalSessions.get(sessionId: string): Promise<ListedPortalSession>

​
Example

const session = await mf.portalSessions.get("ps_a1b2c3d4...");

console.log(session.expiresAt);
The token and url fields are NOT included in this response. Those are only returned by create. The return type is ListedPortalSession, the same shape returned by list. If you need the URL again, mint a new session with create.

​
portalSessions.list

Lists portal sessions your organization has created. Optionally filter to one customer.

​
Signature

await mf.portalSessions.list(params?: ListPortalSessionsParams): Promise<ListedPortalSession[]>

​
Example

// All recent sessions
const sessions = await mf.portalSessions.list();

// Just one customer's sessions, including expired ones
const customerSessions = await mf.portalSessions.list({
  customerId: "550e8400-e29b-41d4-a716-446655440000",
  includeExpired: true,
});

customerSessions.forEach((s) => console.log(s.id, s.isUsed, s.expiresAt));
By default, expired and already-used sessions are filtered out. Set includeExpired: true to see them all.

​
portalSessions.revoke

Immediately invalidates a portal session. Use this if you sent a link to the wrong customer or need to cut access early.

​
Signature

await mf.portalSessions.revoke(sessionId: string): Promise<void>

​
Example

await mf.portalSessions.revoke("ps_a1b2c3d4...");
Once revoked, the link stops working immediately. This is a hard delete. The session can’t be brought back.