Skip to content
Build with Mammoth: open the docs menu

Mammoth board embedding

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

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.

ModeThe boardViewer isSees
publichas a public linkanyonethe whole board
keyno public link; the page presents the board's embed keyanonymous, no viewer identityevery row
signedno public link; every viewer needs a host-signed tokenwhoever your token saysthe 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 descriptionAPI mode
Anyone with the linkShown when the board's Access is Anyone with the linkpublic
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

OperationWhat it doesCLI
GET /dashboards/{id}/embed/configRead a board's embed settings.mammoth dashboard embed config get
PUT /dashboards/{id}/embed/configSave them: mode, origin policy, appearance, snippet shape.mammoth dashboard embed config set
POST /dashboards/{id}/embed/keyCreate or rotate the board's embed key. Editor only.mammoth dashboard embed key rotate
POST /dashboards/{id}/embed/preview-tokenMint a preview token for the simulator. Editor only.mammoth dashboard embed preview-token create
DELETE /dashboards/{id}/embed/originRevoke one origin from the allowlist.mammoth dashboard embed origin revoke
GET /dashboards/{id}/embed/usageWhere this board has been loaded from.mammoth dashboard embed usage get

Per workspace

OperationWhat it doesCLI
POST /workspaces/{id}/embed/secretCreate or rotate the signing secret. Workspace owners and admins only.mammoth dashboard embed secret rotate
PUT /workspaces/{id}/embed/lifetimeHow 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-usageDistinct 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:

{
  "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 and Appearance options.

The signing secret is returned once

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.

FieldWhat it holds
boardThe 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.
expExpiry, in seconds since the epoch. Required. It may be at most the workspace Lifetime from now (Mammoth allows 30 seconds of clock skew).
claimsAn 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):

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.

CodeStatusCauseNotice in the browser console
invalid401Wrong secret, a malformed token, or a missing board or exp"This report could not verify the page's token."
expired401exp has passed"Your session expired."
lifetime_exceeded401exp is further away than the workspace Lifetime allows"This token lasts too long."
board_mismatch403board names a different board"This token is for another board."
missing_claim403No 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 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:

{"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:

Modeiframe 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.

<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.

<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".

OptionWhat it does
containerThe element the iframe goes into.
urlThe board's embed URL.
tokenBasic: 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.
heightLeave 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.
lazyThe iframe loads lazily by default. false loads it straight away.
titleThe iframe's accessible title. Default "Dashboard".
theme, accent, filters, title, kpis, insights, tabs, page, tile, brandingAppearance overrides, added to the URL as query parameters. See 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:

MethodWhat 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.
frameThe 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.

EventWhenPayload
mm-embed-readyThe board has renderedboard (the board's URL slug), pages (a list of {id, title})
mm-embed-sizeThe board's height changedheight in pixels
mm-filter-changeThe viewer changed a filtersummary, state
mm-embed-errorSomething failedcode, 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.

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

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.

KeyValuesDefaultWhat it does
themelight, dark, autolightauto follows the reader's system setting
accenta six-digit hex colour, #2f6feb or 2f6febthe board'sReplaces the primary and first chart colour
title1, 0, true, falseonTitle and standfirst
kpissameonKPI strip
filterssameonFilter bar
insightssameonKey insights
tabssameoffPage tabs. An embed opens on one page; drive the rest with page or setPage
pagea page idthe first pageThe page to open on.
tilea chart idnoneOne chart instead of the whole board
brandingsame as the flagsonThe "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:

FormatOptions
DashboardThis board ("The whole board, filters and all"), One page ("Just this page, no navigation"), One chart ("A single chart, no title or filters")
DocWhole doc, One section
DeckWhole 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. 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:

ActionWarning
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 seesCause
"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.

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.

Next up

Report an issue · support@mammoth.io