Portal Sessions

What is a portal session?

A portal session is a one-time link you send to your customer so they can see their own bill, invoices, subscription, and usage history on a MarginFront-hosted page. Think of it like a Google Doc share link, but for billing. You generate the link on your backend with your secret API key. Your customer clicks it once. They see only their own data. The link works for one hour, then expires.

Why use it?

Let your customers see their invoices and pay (or follow up) without bothering your support team.
Show them their usage and what they’re being billed for, so there are no surprises.
Keep your API key safe. Your customer never sees it.

How it works

You call POST /v1/portal-sessions from your backend.
MarginFront returns a URL like https://portal.marginfront.com/r/mgl_abc123....
You send that URL to your customer (email, SMS, “View my billing” button in your app, whatever fits).
They click it. The link is used up.
They see a MarginFront page branded with your logo and colors showing their invoices, subscription, usage, and profile.
After one hour, they’re logged out.
If anyone tries the same link a second time, they get a “link already used” error.

The endpoints

All four endpoints require a secret API key (mf_sk_...). Publishable keys (mf_pk_...) are rejected with 401 Unauthorized. Always call these from your backend, never from the browser.

Create a portal session

POST /v1/portal-sessions

Request body:

{
  "customerExternalId": "acme-001",
  "returnUrl": "https://your-app.com/billing"
}

Field	Type	Required	Notes
`customerExternalId`	string	One of these two	Your system’s customer ID (the same one you use everywhere else with MarginFront).
`customerId`	string	One of these two	MarginFront’s internal customer UUID. Use this if you already have it.
`returnUrl`	string	No	Stored on the session for your records. The portal does NOT auto-redirect; this is informational.
`features`	string[]	No	Which sections to enable. Valid values: `invoices`, `subscriptions`, `usage`, `profile`. The v1 portal shows all four sections regardless of what you send, so this field is informational only.

Response (201 Created):

{
  "id": "ps_a1b2c3d4...",
  "object": "portal_session",
  "url": "https://portal.marginfront.com/r/mgl_a1b2c3d4...",
  "token": "mgl_a1b2c3d4...",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corp",
  "customerEmail": "[email protected]",
  "expiresAt": "2026-05-13T17:30:00.000Z",
  "createdAt": "2026-05-13T16:30:00.000Z"
}

Give the url to your customer. Save the id if you want to look up or revoke the session later. That’s the only field you’ll need. curl example:

curl -X POST https://api.marginfront.com/v1/portal-sessions \
  -H "x-api-key: mf_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerExternalId": "acme-001",
    "returnUrl": "https://your-app.com/billing"
  }'

Common errors:

400 Bad Request: neither customerId nor customerExternalId was provided.
401 Unauthorized: missing API key, or you sent a publishable (mf_pk_*) key.
404 Not Found: no customer in your org matches the ID you sent.

List portal sessions

GET /v1/portal-sessions

Lists portal sessions your organization has created. Useful for audit or support. For example: “did Acme already open the link I sent yesterday?” Query parameters (all optional):

Param	Type	Default	Notes
`customerId`	string	none	Show only sessions for one customer (internal UUID).
`limit`	number	10	Max 100.
`includeExpired`	boolean	false	Set to `true` to also see expired or already-used sessions.

The token and url fields are NOT returned by this endpoint. Those are only returned at creation. If you lost the URL, mint a new session. Response (200 OK):

[
  {
    "id": "ps_a1b2c3d4...",
    "object": "portal_session",
    "customerId": "550e8400-e29b-41d4-a716-446655440000",
    "customerName": "Acme Corp",
    "customerEmail": "[email protected]",
    "expiresAt": "2026-05-13T17:30:00.000Z",
    "isExpired": false,
    "isUsed": false,
    "createdAt": "2026-05-13T16:30:00.000Z",
    "features": ["invoices", "subscriptions", "usage", "profile"]
  }
]

The response is a flat JSON array. There is no wrapper object and no hasMore field.

Get one portal session

GET /v1/portal-sessions/{sessionId}

Returns one session’s details: customer, expiry, whether it’s been used yet. The token and url are NOT included. You only get those at creation time. Returns 404 Not Found if the session doesn’t exist or belongs to another organization. Response (200 OK):

{
  "id": "ps_a1b2c3d4...",
  "object": "portal_session",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corp",
  "customerEmail": "[email protected]",
  "expiresAt": "2026-05-13T17:30:00.000Z",
  "isExpired": false,
  "isUsed": true,
  "usedAt": "2026-05-13T16:45:12.000Z",
  "createdAt": "2026-05-13T16:30:00.000Z",
  "features": ["invoices", "subscriptions", "usage", "profile"]
}

Revoke a portal session

DELETE /v1/portal-sessions/{sessionId}

Immediately invalidates the link. Use this if you sent a link to the wrong customer or your support team needs to cut access early. Returns 204 No Content on success, 404 Not Found if the session doesn’t exist.

Security notes

Always mint links on your backend. Portal sessions require a secret key. Treat that key like a database password.
One link, one click. The link is consumed on first open. Anyone (including the original customer) who tries it a second time gets an error.
Tokens are only shown once. The token and url fields are returned only by create. Lost URLs cannot be retrieved; revoke and mint a new session.
Need to cut access early? Use the revoke endpoint. It works immediately.

Resources

Reference

Portal Sessions

Portal Sessions

What is a portal session?

Why use it?

How it works

The endpoints

Create a portal session

List portal sessions

Get one portal session

Revoke a portal session

Security notes

​Portal Sessions

​What is a portal session?

​Why use it?

​How it works

​The endpoints

​Create a portal session

​List portal sessions

​Get one portal session

​Revoke a portal session

​Security notes

Portal Sessions

What is a portal session?

Why use it?

How it works

The endpoints

Create a portal session

List portal sessions

Get one portal session

Revoke a portal session

Security notes