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.
| 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:
{
"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/originreturns 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):
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 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:
| 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.
<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".
| 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. 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.
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.
| 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_previouschoice). 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,claimsandexplines), 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:
| 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.
Order of operations
- Publish the board. An unpublished board has nothing to frame.
- Decide the mode. Leave it
keyunless a viewer must see only their own rows. - For
signed: rotate the workspace secret, store the plaintext, set the session lifetime. - Close the origin policy if you need it closed:
allow_any_origin: falseplusallowed_origins. - Check a scope with a preview token before writing the signing into your backend.
- Read usage after the page is live, as a floor.
Next up
- Authentication: API tokens, and where credentials belong.
- Command contract: every command, with its blast radius and endpoint.