@tolt/embed

<ToltEmbed /> renders a partner’s referral dashboard (link, earnings, customers) inside your app. For a step-by-step walkthrough, see Refer-a-friend page.

Your app

Your servertoken route

Toltplatform.tolt.com

1/api/tolt/embed-token

2POST /v2/embed-tokens

4token

5iframe /referrals?token=…

6tolt-embed:ready

Install

npm install @tolt/embed

Requires React 17 or later. Without React, use the iframe directly.

1. Mint a token on your server

Your API key never reaches the browser. Your backend exchanges it for a token scoped to one partner, valid for about an hour; read expires_at.

import { ToltApiClient } from "@tolt/api";

const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });

export async function GET() {
  const user = await getCurrentUser(); // your auth
  const { data } = await tolt.embedTokens.create({
    partner: {
      email: user.email,
      program_id: "prg_2wXc4VnB8mQz6RtLp9KsYd3F",
    },
  });
  return Response.json({ token: data.token, expires_at: data.expires_at });
}

partner = {"email": user.email, "program_id": "prg_2wXc4VnB8mQz6RtLp9KsYd3F"}
token = client.embed_tokens.create(partner=partner).data.token

curl -X POST https://platform.tolt.com/v2/embed-tokens \
  -H "Authorization: Bearer $TOLT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partner_id": "part_8fKq2LmZx7RtYw3nVbHc5dPj"}'

Send exactly one of partner_id or partner: { email, program_id }. With partner, Tolt finds the partner by email in the program, or creates them (active, with a referral link) when there is none; add first_name and last_name to name a new partner. partner_id only finds an existing partner. Either way you get 404 for a partner who is invited, suspended or rejected, or a program that isn’t active. The response includes the partner_id the token is for.

2. Render the component

referrals.tsx

"use client";

import { useEffect, useState } from "react";
import { ToltEmbed } from "@tolt/embed";

export function Referrals() {
  const [token, setToken] = useState<string>();

  const load = async () => {
    const res = await fetch("/api/tolt/embed-token");
    setToken((await res.json()).token);
  };

  useEffect(() => {
    load();
  }, []);

  if (!token) return null;

  return (
    <ToltEmbed
      token={token}
      theme="system"
      themeOptions={{ brandColor: "#4f46e5", radius: 10 }}
      onError={() => load()}
    />
  );
}

Wait for the token before rendering. Without token, the component shows a sample dashboard with demo data.

Props

string

The embed token from your server. Omit it to render a sample dashboard (useful while designing).

"light" | "dark" | "system"

default:"system"

Force a color scheme, or follow the partner’s system setting.

ToltEmbedThemeOptions

Match the dashboard to your brand. Every key is optional; anything you leave out keeps the default for the active theme.

Show theme options

string

Accent: the copy button, links and the earnings sparkline.

string

Text and icons on top of brandColor.

string

The dashboard card surface.

string

Raised tiles inside the card: stats and the referral link field.

string

Primary text.

string

Secondary text and labels.

string

Hairline borders and dividers.

number | string

Corner radius. A number is pixels; a string is used as is.

string

Body font stack.

string

Heading font stack.

"referrals"

default:"referrals"

Which embed to render. The referral dashboard is the only one today.

() => void

Fires once the dashboard has loaded and reported its size.

(message: string) => void

Fires if the dashboard fails to load, for example because the token had already expired. Fetch a new token here. A dashboard that has loaded doesn’t re-check its token, so for long sessions fetch a new one before expires_at.

string

Class name for the iframe.

CSSProperties

Inline styles for the iframe, merged over the defaults (width: 100%, no border).

string

default:"https://platform.tolt.com"

Override the embed host. Mostly for local development.

The iframe starts 520px tall and then resizes itself to fit its content.

Iframe without React

Point an iframe at /referrals with the token and any theme options as query params:

<iframe
  src="https://platform.tolt.com/referrals?token=TOKEN&theme=dark"
  allow="clipboard-write"
  style="width: 100%; height: 640px; border: 0"
></iframe>

A raw iframe does not resize itself. To match the component, listen for its messages:

`event.data.type`	Payload
`tolt-embed:ready`		The dashboard loaded.
`tolt-embed:resize`	`height` (px)	Set the iframe height to this.
`tolt-embed:error`	`message`	The token was rejected or loading failed.

window.addEventListener("message", (event) => {
  if (event.origin !== "https://platform.tolt.com") return;
  if (event.data?.type === "tolt-embed:resize") {
    iframe.style.height = `${event.data.height}px`;
  }
});

Overview

Server SDKs

Browser

Partner experiences

Tooling and AI

Install

1. Mint a token on your server

2. Render the component

Props

Iframe without React

​Install

​1. Mint a token on your server

​2. Render the component

​Props

​Iframe without React

Install

1. Mint a token on your server

2. Render the component

Props

Iframe without React