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 regardless of plan. Availability of the attribution mark—whether a "Built with Mammoth" footer appears—depends on your plan; check with your admin. A board with a public link embeds over that link whatever mode is saved.
Who can change what
Two different permissions, and mixing them up is the first thing to get wrong. Board settings are an editor's. The workspace signing secret and the session lifetime are an owner's or admin's.
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. 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. | mammoth dashboard embed lifetime set |
GET /workspaces/{id}/dashboards/embed-usage | Distinct origins per board over the last 90 days. | REST only |
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 mode, and the preview token
In signed mode your server mints a token per viewer, carrying claims keyed by the board's row-level-security rules. A signed token may not outlive the workspace session lifetime, so the 60–3600 second setting caps both.
POST .../embed/preview-token exists so an author can see the board under a given scope without ever holding the secret: it signs server-side with the workspace secret and is editor-only. Use it to check a scope before you build the signing into your backend.
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), or a pixel count from 240 to 2400. appearance carries the saved look applied on load, including tile to embed one chart instead of the whole board.
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.