> ## 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

> Mint, look up, and revoke customer portal links from the Node SDK.

# 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](/api-reference/portal-sessions) for a plain-English explanation of what they are and why you'd use them.

***

## Setup

```typescript theme={null}
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

```typescript theme={null}
await mf.portalSessions.create(params: CreatePortalSessionParams): Promise<PortalSession>
```

### Example

```typescript theme={null}
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](/api-reference/portal-sessions) 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

```typescript theme={null}
await mf.portalSessions.get(sessionId: string): Promise<ListedPortalSession>
```

### Example

```typescript theme={null}
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

```typescript theme={null}
await mf.portalSessions.list(params?: ListPortalSessionsParams): Promise<ListedPortalSession[]>
```

### Example

```typescript theme={null}
// 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

```typescript theme={null}
await mf.portalSessions.revoke(sessionId: string): Promise<void>
```

### Example

```typescript theme={null}
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.