> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @tolt/embed

> Reference for the embeddable partner dashboard: props, theme options, the token endpoint and iframe usage.

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

Your app\<ToltEmbed />Your servertoken routeToltplatform.tolt.com*1*/api/tolt/embed-token*2*POST /v2/embed-tokens*3*\{ token, expires\_at }*4*token*5*iframe /referrals?token=…*6*tolt-embed:ready

## Install

```bash theme={"system"}
npm install @tolt/embed
```

Requires React 17 or later. Without React, use the [iframe](#iframe-without-react) 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`.

```ts TypeScript theme={"system"}
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 });
}
```

```python Python theme={"system"}
partner = {"email": user.email, "program_id": "prg_2wXc4VnB8mQz6RtLp9KsYd3F"}
token = client.embed_tokens.create(partner=partner).data.token
```

```bash cURL theme={"system"}
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

```tsx referrals.tsx theme={"system"}
"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()}
    />
  );
}
```

> [!WARNING]
>
> Wait for the token before rendering. Without `token`, the component shows a sample dashboard with demo data.

## Props

**token** `string`

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

**theme** `"light" | "dark" | "system"` (default: system)

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

**themeOptions** `ToltEmbedThemeOptions`

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

**theme options**

**brandColor** `string`

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

**brandTextColor** `string`

Text and icons on top of `brandColor`.

**backgroundColor** `string`

The dashboard card surface.

**surfaceColor** `string`

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

**textColor** `string`

Primary text.

**mutedColor** `string`

Secondary text and labels.

**borderColor** `string`

Hairline borders and dividers.

**radius** `number | string`

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

**fontFamily** `string`

Body font stack.

**headingFontFamily** `string`

Heading font stack.

**data** `"referrals"` (default: referrals)

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

**onReady** `() =\> void`

Fires once the dashboard has loaded and reported its size.

**onError** `(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`.

**className** `string`

Class name for the iframe.

**style** `CSSProperties`

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

**baseUrl** `string` (default: [https://platform.tolt.com](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:

```html theme={"system"}
<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. |

```js theme={"system"}
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`;
  }
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.