> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Mammoth board embedding

> Embed a Mammoth board in your page. The three modes, signed tokens, the JavaScript SDK and its events, appearance options, the Embed panel and nine API operations.

A Mammoth board inside a page you control, scoped to a viewer who has no Mammoth account and never signs in.

> **Every operation has a command**
>
> All nine operations below have a `mammoth dashboard embed` command, and each has a matching `client.dashboards.embed_*` method in the Python SDK, so you rarely need to call them over HTTP yourself.

## The three modes

**Every published board embeds.** The mode is not a switch that turns embedding on. It decides what a board *without* a public link demands from the page framing it.

| Mode | The board | Viewer is | Sees |
| --- | --- | --- | --- |
| `public` | has a public link | anyone | the whole board |
| `key` | no public link; the page presents the board's embed key | anonymous, no viewer identity | every row |
| `signed` | no public link; every viewer needs a host-signed token | whoever your token says | the rows your claims allow |

All three modes are available on every plan: Free, Starter, Team and Pro. The "Made with Mammoth" attribution mark stays on for boards in Free and Starter workspaces, and during a trial. On Team and Pro you can turn it off. A board with a public link embeds over that link whatever `mode` is saved. Showing each viewer only their own rows needs row-level security on the board, which is included on the Pro plan.

The Embed panel in the app uses its own words for these modes:

| Embed panel (**Who should be able to see it**) | Panel description | API `mode` |
| --- | --- | --- |
| **Anyone with the link** | Shown when the board's Access is **Anyone with the link** | `public` |
| **Basic**, "Anyone who can open my site" | "A key you paste into the page. Every row, no sign-in." | `key` |
| **Advanced**, "Only people I identify" | "Your server signs a token per viewer. Optionally, each viewer sees only their rows." | `signed` |

In the panel the attribution toggle is simply greyed out on Free and Starter and during a trial; it carries no upgrade prompt.

## Who can change what

Two different permissions, and mixing them up is the first thing to get wrong. Board settings are an editor's: anyone with edit access to the board. The workspace signing secret and the session lifetime belong to the workspace: over the API a workspace owner or admin can set them, and in the Embed panel only a workspace owner can. In the Embed panel, anyone else sees "Only a workspace owner can generate the signing secret." and the **Advanced** option reads "Needs a workspace owner to set up signing".

## The nine operations

The commands take the board id as the first argument, or the workspace id for the two workspace commands. `config set`, `key rotate`, `origin revoke` and `secret rotate` need `--yes --confirm ID`, repeating that id. `lifetime set` and `preview-token create` need no confirmation. `mammoth schema get <command.id>` shows each command's input.

### Per board

| Operation | What it does | CLI |
| --- | --- | --- |
| `GET /dashboards/{id}/embed/config` | Read a board's embed settings. | `mammoth dashboard embed config get` |
| `PUT /dashboards/{id}/embed/config` | Save them: mode, origin policy, appearance, snippet shape. | `mammoth dashboard embed config set` |
| `POST /dashboards/{id}/embed/key` | Create or rotate the board's embed key. Editor only. | `mammoth dashboard embed key rotate` |
| `POST /dashboards/{id}/embed/preview-token` | Mint a preview token for the simulator. Editor only. | `mammoth dashboard embed preview-token create` |
| `DELETE /dashboards/{id}/embed/origin` | Revoke one origin from the allowlist. | `mammoth dashboard embed origin revoke` |
| `GET /dashboards/{id}/embed/usage` | Where this board has been loaded from. | `mammoth dashboard embed usage get` |

### Per workspace

| Operation | What it does | CLI |
| --- | --- | --- |
| `POST /workspaces/{id}/embed/secret` | Create or rotate the signing secret. Workspace owners and admins only. | `mammoth dashboard embed secret rotate` |
| `PUT /workspaces/{id}/embed/lifetime` | How long an embed viewer session lives, 60 to 3600 seconds. Workspace owners and admins only. | `mammoth dashboard embed lifetime set` |
| `GET /workspaces/{id}/dashboards/embed-usage` | Distinct origins per board over the last 90 days. | `mammoth dashboard embed usage summary` |

### Saving a board's settings

`PUT /dashboards/{id}/embed/config` takes the settings under `params`. Every field is optional:

```json
{
  "params": {
    "mode": "signed",
    "allow_any_origin": false,
    "allowed_origins": ["https://app.example.com", "https://*.example.com"],
    "snippet": {"height": "auto"}
  }
}
```

`mode` is `key` (the default) or `signed`. A field you leave out keeps its saved value, so a save that sends only `allowed_origins` never moves an Advanced board back to Basic. Choosing `signed` on a board with a public link is refused: a public board embeds over its link. A board on `key` gets its embed key the first time an editor reads or saves its settings. `appearance` and `snippet` are described under [Snippet shape](#snippet-shape) and [Appearance options](#appearance-options).

## The signing secret is returned once

> **No read route ever includes the secret**
>
> `POST /workspaces/{id}/embed/secret` returns the plaintext secret **once**. Nothing reads it back, and the route is excluded from the request log. Store it the way you store `MAMMOTH_API_TOKEN`: in the environment, never in a prompt, a script or a repository file.

Rotating keeps the previous secret valid for **24 hours**, so a rotation does not invalidate every live token at once. The board-level embed key behaves the same way and for the same reason; send `keep_previous: false` to end the old one immediately.

## Framing is open until you close it

`allow_any_origin` defaults to **true**. Any site may frame the board until you set it false, and only then does `allowed_origins` restrict anything.

- Patterns are `https://host[:port]`, with one leading `*.` label allowed.
- Normalised and de-duplicated, at most 20 per board.
- `DELETE .../embed/origin` returns **400** while the board is open to any site. There is no list to take a site off.

## A page opened from a file cannot frame a board

A page opened straight from disk (a `file://` address) cannot frame an embed. The embed response allows framing with `frame-ancestors *`, and that rule matches only `http` and `https` pages. This is a browser rule, so no board setting changes it. Serve the test page over `http://localhost` or from your real site instead.

## Signed tokens for Advanced embeds

In `signed` mode your server mints a token for each viewer. The token is a JWT signed with **HS256** over the workspace signing secret. Mammoth accepts no other algorithm.

### The token payload

The whole payload is three fields. Anything else (`iat`, `sub`, a viewer id) is ignored.

| Field | What it holds |
| --- | --- |
| `board` | The board's URL slug: the last part of its embed URL, after `/embed/`. The **2 · Sign a token on your server** step in the Embed panel shows it filled in for this board. |
| `exp` | Expiry, in seconds since the epoch. Required. It may be at most the workspace **Lifetime** from now (Mammoth allows 30 seconds of clock skew). |
| `claims` | An object keyed by the board's row-level-security column name, spelled exactly as stored (`"Company"` does not answer for `"company"`). The value is a non-empty string or a non-empty list of strings. Numbers are refused: send `"882"`, not `882`. Leave `claims` out when the board has no row-level security. |

A Node example, the same shape the Embed panel shows (any JWT library works):

```js
const jwt = require('jsonwebtoken')

const token = jwt.sign(
  { board: '<board_url>', claims: { Region: user.region } },
  process.env.MAMMOTH_SIGNING_SECRET,
  { algorithm: 'HS256', expiresIn: 300 } // at most the workspace Lifetime
)
```

While the board has a live row-level-security column, every token must carry a value for it. Without row-level security the panel says "Row-level security is off, so every viewer with a valid token sees the whole board."

### Why a token is refused

Mammoth checks a token in this order: signature, expiry, lifetime, board, the row claim. The first failure decides the code.

| Code | Status | Cause | Notice in the browser console |
| --- | --- | --- | --- |
| `invalid` | 401 | Wrong secret, a malformed token, or a missing `board` or `exp` | "This report could not verify the page's token." |
| `expired` | 401 | `exp` has passed | "Your session expired." |
| `lifetime_exceeded` | 401 | `exp` is further away than the workspace **Lifetime** allows | "This token lasts too long." |
| `board_mismatch` | 403 | `board` names a different board | "This token is for another board." |
| `missing_claim` | 403 | No usable value for the board's row-level-security column | "This report needs more information about you." |

A Basic embed has one credential, so it has two refusals: a wrong key (401, "This report needs a valid key.") and a board with row-level security (403 `needs_signed`, "This report needs a signed token."), because a key carries no viewer.

The secret you rotated away from keeps signing valid tokens for 24 hours. Too many new sessions in a minute returns 429 (see [Embed with a plain iframe](#embed-with-a-plain-iframe) for the limits).

### Preview as viewer

`POST /dashboards/{id}/embed/preview-token` lets an editor see the board under a given scope *without ever holding the secret*. Mammoth signs the token server-side with the workspace secret, for the workspace lifetime. Send the claims under `params`:

```json
{"params": {"claims": {"Region": "EMEA"}}}
```

The response carries `token`, `expires_at` and `embed_url`. Before the workspace has a signing secret, the call is refused with the detail `no_secret`. In the Embed panel this is **Preview as viewer** under **Advanced**.

## Embed with a plain iframe

You don't need the SDK. A plain `<iframe>` carries its credential in the URL:

| Mode | iframe `src` |
| --- | --- |
| Public link | `<embed_url>` |
| Basic | `<embed_url>?key=<embed_key>` |
| Advanced | `<embed_url>?token=<signed_token>`, where your server renders the page with a token it signed for this viewer (at most 4096 characters) |

`<embed_url>` is the `embed_url` in the board's embed config, the same address the Embed panel's snippet uses. Copy it from there rather than building it.

```html
<iframe
  src="<embed_url>?key=<embed_key>"
  width="100%" height="640"
  frameborder="0" loading="lazy"
  allow="clipboard-write; fullscreen"
  title="Embedded dashboard">
</iframe>
```

The frame trades the key or token for a short viewer session, then loads the board. A Basic session lasts the workspace **Lifetime** (5 minutes until you set one). An Advanced session ends when its token's `exp` passes. Before a Basic session ends, the frame renews it on its own with the same key. An Advanced frame can't mint a new token itself: with no SDK to ask, the reader sees "This session has ended." / "Reload the page to continue."

Each board accepts up to 120 new Basic sessions a minute in total, and up to 120 Advanced sessions a minute from one address. Renewals count.

## The JavaScript SDK (MammothEmbed)

The SDK is a small loader. It creates the iframe, does the handshake with the board, grows the frame to the board's height, and hands over the key or token. It never renders the board itself. The Embed panel's snippet uses it when **Height** is **Auto**.

```html
<div id="mm-dashboard"></div>
<script src="<sdk_url>"></script>
<script>
  const embed = MammothEmbed.create({
    container: document.getElementById('mm-dashboard'),
    url: '<embed_url>',
    token: () => fetch('/mammoth-token').then((r) => r.text()),
    theme: 'auto',
    onEvent: (type, payload) => console.log(type, payload)
  })
</script>
```

`<sdk_url>` is the `sdk_url` in the board's embed config. The script lives at `/embed-assets/sdk.v1.js` on the embed host and defines the global `MammothEmbed`.

### Options for MammothEmbed.create

`container` and `url` are required. Without them `create` throws "MammothEmbed.create needs container and url".

| Option | What it does |
| --- | --- |
| `container` | The element the iframe goes into. |
| `url` | The board's embed URL. |
| `token` | Basic: the embed key as a string. Advanced: a function that returns a signed token (or a promise of one). The SDK calls it again when the session expires, at most once every 30 seconds. |
| `height` | Leave it out (or `'auto'`) to grow the frame to the board. A number is the starting height in pixels (default 480). `'fixed'` keeps the frame at 480 pixels. For another fixed height, use the plain iframe. |
| `lazy` | The iframe loads lazily by default. `false` loads it straight away. |
| `title` | The iframe's accessible title. Default "Dashboard". |
| `theme`, `accent`, `filters`, `title`, `kpis`, `insights`, `tabs`, `page`, `tile`, `branding` | Appearance overrides, added to the URL as query parameters. See [Appearance options](#appearance-options). `true` and `false` become `1` and `0`. |
| `onEvent` | `(type, payload) => {}`, called for every event from the board. |

`title` does double duty. A string names the frame. `false` hides the title band and leaves the frame named "Dashboard".

### Methods

`create` returns an object with:

| Method | What it does |
| --- | --- |
| `setFilter(filters)` | Replaces the board's filter selection. Same shape as `state` in `mm-filter-change`: each filter field maps to a list of values, or to a range object. Fields you leave out are cleared. |
| `setPage(pageId)` | Opens a page by id. The ids come in the `pages` list of `mm-embed-ready`. |
| `setTheme(theme, accent)` | Switches to `light`, `dark` or `auto`, and optionally a new accent. The viewer keeps their page and filters. |
| `on(type, fn)` | Adds a listener for one event type. Returns the embed, so calls chain. |
| `destroy()` | Removes the iframe and the listeners. |
| `frame` | The iframe element. |

### Events

Every event from the board carries `v: 1`, the protocol version. The two errors the SDK raises itself (`token_fetch_failed` and `not_ready`) don't.

| Event | When | Payload |
| --- | --- | --- |
| `mm-embed-ready` | The board has rendered | `board` (the board's URL slug), `pages` (a list of `{id, title}`) |
| `mm-embed-size` | The board's height changed | `height` in pixels |
| `mm-filter-change` | The viewer changed a filter | `summary`, `state` |
| `mm-embed-error` | Something failed | `code`, `message` |

`mm-embed-error` codes include the token refusals above (`expired` arrives as `token_expired`), `token_rejected` for any other refusal, `unavailable` (unpublished or revoked), `load_failed`, `token_fetch_failed` (your `token` function failed) and `not_ready`.

### When the site isn't allowed

If the board doesn't answer within 8 seconds, usually because your site isn't on its allowed list, the SDK replaces the frame with a notice: "This board isn't allowed here." / "The board's owner needs to allow this site before it can appear." It shows your site's address with a **Copy site address** button, so you can send it to the board's owner. It also fires `mm-embed-error` with the code `not_ready`.

A plain iframe without the SDK gets no messages from the board at all: the board only talks to a page that has said hello through the SDK.

## How an embedded board fits the page

A whole board is laid out at the width it was designed at (1440 pixels) and scaled to your frame, so readers see the arrangement the author built. Between 700 and 1440 pixels wide it shrinks to fit. Wider than 1440 it grows, up to one and a half times. Below 700 pixels it switches to the phone layout instead of shrinking. A single chart takes your frame's width as given. A doc reflows at your width, and a deck fills the frame and scales its slides.

## What usage data can and cannot tell you

`GET .../embed/usage` returns one row per origin and tile, with rolling render counts, health, and whether the origin is still on the allowlist.

> **Observed, not known**
>
> The registry is built from render beacons. It records where a board **has been loaded from**, which is not the same as where it has been embedded: a snippet pasted into a page nobody has opened does not appear. Read it as a floor, never a count.

## Snippet shape

`snippet.height` is `auto` (the SDK grows the frame), `aspect` (16:9), `slide` (16:10), or a pixel count from 240 to 2400. Any other value is dropped, and the panel falls back to 640 pixels. `appearance` carries the saved look applied on load; see [Appearance options](#appearance-options).

## Appearance options

A board's saved `appearance` sets the defaults. A page can override any of them with a query parameter on the embed URL (or the matching SDK option). Mammoth reads only the keys below and drops anything else, or any value it can't read, without an error.

| Key | Values | Default | What it does |
| --- | --- | --- | --- |
| `theme` | `light`, `dark`, `auto` | `light` | `auto` follows the reader's system setting |
| `accent` | a six-digit hex colour, `#2f6feb` or `2f6feb` | the board's | Replaces the primary and first chart colour |
| `title` | `1`, `0`, `true`, `false` | on | Title and standfirst |
| `kpis` | same | on | KPI strip |
| `filters` | same | on | Filter bar |
| `insights` | same | on | Key insights |
| `tabs` | same | off | Page tabs. An embed opens on one page; drive the rest with `page` or `setPage` |
| `page` | a page id | the first page | The page to open on. |
| `tile` | a chart id | none | One chart instead of the whole board |
| `branding` | same as the flags | on | The "Made with Mammoth" mark. `0` works only on Team and Pro, outside a trial; elsewhere the mark stays |

For example, `<embed_url>?theme=dark&filters=0&page=p2` opens page `p2` in dark mode without the filter bar.

The title band, KPI strip, filter bar, Key insights and page tabs exist only on a whole dashboard. A single chart, a doc, a deck or a motion story ignores those keys; theme, accent and the mark still apply. Docs and decks embed in their own format (a reading column, the slide player). Every other board style embeds as a dashboard.

A `tile` the published board doesn't have shows "This chart is no longer part of this report." / "It was removed or replaced by the author." Mammoth never swaps in another chart.

## The Embed panel

Everything on this page can be set without the API. In the app, open the board's **Share** panel and pick the **Embed** tab at the top, next to **Share**. The same tab opens from the editor's **Publish** caret → **Embed**, a library row's **⋯** → **Embed**, the frame icon on a tile, and the editor header badge **Embedded · 2**.

The panel drafts your changes: it shows **Unsaved changes** with **Discard** / **Apply**, and asks "Apply your changes before leaving?" if you close it. Managing embedding needs edit access to the board ("You need edit access to manage embedding."). An unpublished board shows **Embed in a page**, "Publish the board first", and a **Publish and embed** button, which is greyed out on sample data.

### Scope: what goes in the page

**What goes in the page?** maps to the `appearance` you save:

| Format | Options |
| --- | --- |
| Dashboard | **This board** ("The whole board, filters and all"), **One page** ("Just this page, no navigation"), **One chart** ("A single chart, no title or filters") |
| Doc | **Whole doc**, **One section** |
| Deck | **Whole deck** ("Every slide, with arrows"), **One slide** |

**Opens on** / **Start on** picks the first page: **First page** or a named page. Only published pages appear: "Pages you add later show up here once you publish them." The Q&A page is never embedded ("The Q&A page isn't included in embeds.").

Shortcut for one chart: on a board with a public link or **Basic** security, the frame icon on a tile copies a one-chart snippet straight away ("Embed code copied. Paste it in any page." with **Options**). Otherwise it opens this panel with that tile picked.

### Security: Basic key and Advanced tokens

Under **Who sees it**:

- **Basic** shows the **Embed key** with **Show** / **Hide**, **Generate key** and **Rotate**. Rotating offers **Rotate, keep 24h** or **Rotate, end now** (the `keep_previous` choice). Anyone who can read the host page can read the key, so the allowed sites are what limit it. If the board has row-level security, a key shows no rows: "This board has row rules; a key carries no viewer, so use Advanced."
- **Advanced** walks three steps: **1 · Signing secret** (**Generate secret** / **Rotate**; "Copy this now. It is shown once and cannot be read again."), **2 · Sign a token on your server** (a Node example with the `board`, `claims` and `exp` lines), and **3 · Hand the token to the page** (through the SDK, or `?token=` in the iframe URL). Then **Preview as viewer** signs a preview token for a value you type, and **Lifetime** sets the session length in minutes, 1 to 60. Without row-level security: "Row-level security is off, so every viewer with a valid token sees the whole board."

A plain iframe shows a reload notice when an Advanced token expires. The SDK fetches a fresh one without the reader noticing.

### Allowed sites and revoke

**Which sites** → **Where it can be framed** is **Any site** (the default; "Any page may frame this board. The key or token, if any, still applies.") or **Only these sites**. Add each origin with **Add a domain**, in the patterns described under [Framing is open until you close it](#framing-is-open-until-you-close-it). A site that tried and was refused appears as "shop.example.com — blocked" with **Allow**.

### Appearance and size

**How it looks** (collapsed, with "2 hidden" when you've hidden parts):

- **Theme**: **Auto** ("Light or dark, from the reader's system setting."), **Light** or **Dark**
- **What shows**: **Title & standfirst**, **KPI strip**, **Filter bar** (the viewer can filter), **Key insights**, and the **"Made with Mammoth"** attribution. Parts the board doesn't have are greyed out ("This board has no KPI strip"). A single chart, doc, deck or motion story has no title band, KPI strip, filter bar or page tabs; theme and the mark still apply.

**Height** maps to `snippet.height`: **Auto** ("Grows with the board. Needs our 3-line script."), **Aspect** (16:9), **Slide shape** (16:10), or **Fixed** with **Height in px**. Auto isn't offered for decks. An iframe can't size itself to its content, so Auto works only with the script in the snippet.

### The snippet

**Paste this where you want the board** ("Works in any HTML page — your site, an intranet, Notion, Confluence.") lists what **This snippet sets**, then "Everything else follows the board." Click **Copy snippet**. A pasted snippet keeps the choices it was copied with. Plain links follow the board's defaults.

### Where it's showing

**Where it's showing** reads "Not seen on a site yet" or "2 sites" with **See where**. The same list is the **Embeds** tab in the library's details panel. It shows **Sites**, **Tiles embedded**, **Loads · 7d** and **Refused · 30d**, then one row per site with its scope ("Whole board" or "Tile 3"), "140 loads in 7 days", "last seen 2 hours ago", health (**OK**, **Errors**, **Refused** or **Revoked**) and **Open**. **Revoke** takes a site off the allowed list (`DELETE .../embed/origin`). This is the same render-beacon data as `GET .../embed/usage`, so read it as a floor.

## Guardrails before an embed breaks

Mammoth warns before an action breaks a live embed:

| Action | Warning |
| --- | --- |
| Unpublish (Share panel) | "Unpublishing breaks 2 embeds: intranet.example.com, wiki.example.com". You must tick **I understand embeds will stop working** |
| Delete a tile (editor) | "This tile is embedded" / "Removing this tile breaks 2 embeds: intranet.example.com, wiki.example.com" / "Their pages will keep loading — only this chart disappears." |
| Delete the board (library) | "Deleting breaks 2 embeds: intranet.example.com, wiki.example.com" |

While you edit an embedded board, a banner reads "Embedded in 2 places — they show the published version." With unpublished changes, it reads "…they update when you publish." Embeds always show the published version.

## What readers see when an embed fails

Readers never see the integration error. They see a generic message, and the precise reason goes to the host page: as an `mm-embed-error` event for the SDK, and as a browser console warning that starts with `[Mammoth embed]` and ends with the code, for example `(code: board_mismatch)`.

| Reader sees | Cause |
| --- | --- |
| "This report isn't available." / "It was unpublished, or the link was revoked." | The board was unpublished or the origin revoked |
| "This dashboard could not be loaded." / "Try again in a moment." | A transient failure |
| "This session has ended." / "Reload the page to continue." | The viewer session ended and no new token came: a plain Advanced iframe, or an SDK `token` function that didn't answer within 8 seconds |
| "This embed needs a newer viewer." | An outdated snippet |
| "This report isn't available right now." / "Check back shortly, or ask whoever added it to this page." | An integration fault: invalid key, a signed token required, a missing claim, a token that outlives the lifetime, a token for another board, or a rejected token |

The snippet carries a no-script fallback with the board's title and link; it includes headline numbers only for public boards without row-level security. A plain share link (not `/embed/`) framed in another site shows "This dashboard can't be shown inside another site." with **Open in Mammoth**. For the full reader side, see [What dashboard viewers see](https://mammoth.io/docs/learn/share-and-export/what-viewers-see/).

## Order of operations

1. Publish the board. An unpublished board has nothing to frame.
2. Decide the mode. Leave it `key` unless a viewer must see only their own rows.
3. For `signed`: rotate the workspace secret, store the plaintext, set the session lifetime.
4. Close the origin policy if you need it closed: `allow_any_origin: false` plus `allowed_origins`.
5. Check a scope with a preview token before writing the signing into your backend.
6. Read usage after the page is live, as a floor.

> **Verify against the API**
>
> The OpenAPI document is authoritative where this page summarises it. It needs your token: `curl -H "Authorization: Bearer $MAMMOTH_API_TOKEN" https://app.mammoth.io/api/v2/docs/openapi.json`. `mammoth schema get <command.id>` shows each command's input.

## Next up

- [Authentication](https://mammoth.io/docs/build/auth/): API tokens, and where credentials belong.
- [Command contract](https://mammoth.io/docs/build/): every command, with its blast radius and endpoint.

---
Source: https://mammoth.io/docs/build/embedding.md · Updated: 2026-11-02
