Documentation Index
Fetch the complete documentation index at: https://docs.marginfront.com/llms.txt
Use this file to discover all available pages before exploring further.
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:
- Creating a portal session
- Getting one portal session
- Listing portal sessions
- 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);
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.).
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);
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));
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...");
