Embedded Portal

The embedded portal lets your partners see their referral stats, copy their unique link, and connect their Stripe account for payouts — all without leaving your app. It's rendered as an iframe using a short-lived token you generate server-side.

How it works

1. Your server calls embedTokens.create() to generate a public token for a specific partner
2. You pass that token to the <RefportEmbed> React component (or build your own iframe)
3. The portal renders inside your app, sized dynamically to its content

Tokens expire after a short period (check token.expires), so generate a fresh one on each page load or session.

Setup

npm install refport @refport/react

import { Refport } from 'refport';

const refport = new Refport({ apiKey: process.env.REFPORT_API_KEY! });

export async function GET(req: Request) {
  const user = await getCurrentUser(req); // your auth logic

  const token = await refport.embedTokens.create({
    tenantId: user.id,
    partner: {
      email: user.email,
      name: user.name,
    },
  });

  return Response.json({ token: token.publicToken });
}

import { RefportEmbed } from '@refport/react';

async function getEmbedToken(): Promise<string> {
  const res = await fetch('/api/embed-token');
  const data = await res.json();
  return data.token;
}

export default async function ReferralsPage() {
  const token = await getEmbedToken();

  return (
    <div className="max-w-2xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Your Referrals</h1>
      <RefportEmbed token={token} theme="system" />
    </div>
  );
}

Customising the portal appearance

Theme

Pass theme="light", theme="dark", or theme="system" to match your app's color scheme:

<RefportEmbed token={token} theme="dark" />

Theme overrides

Override individual colors to match your brand:

<RefportEmbed
  token={token}
  themeOptions={{
    backgroundColor: '#0f172a',
    primaryColor: '#6366f1',
    textColor: '#f1f5f9',
  }}
/>

CSS variables

For fine-grained control, inject CSS variables directly into the portal iframe:

<RefportEmbed
  token={token}
  cssVars={{
    '--font-family': 'Inter, sans-serif',
    '--border-radius': '0.5rem',
  }}
/>

Handling portal errors

Use the onError prop to react to errors reported by the portal (e.g. expired token):

<RefportEmbed
  token={token}
  onError={({ code, message }) => {
    if (code === 'TOKEN_EXPIRED') {
      // refetch the token and re-render
    }
    console.error(code, message);
  }}
/>

Token parameters

See embedTokens.create() in the Node.js SDK reference for all available parameters.

Using without React

If you're not using React, build the iframe URL manually and render it yourself:

const params = new URLSearchParams({
  token: publicToken,
  theme: 'system',
  dynamicHeight: 'true',
});

const iframeSrc = `https://app.refport.co/embed/referrals?${params}`;

Listen to window.postMessage events from the iframe for PAGE_HEIGHT (to resize the iframe) and ERROR events.