A live embed, not a snapshot

Embedding a Page gives you an <iframe>you paste into your own marketing site, partner portal, internal wiki — anywhere that renders HTML. What it shows is the real Page, rendered live: the host runs the Page’s declared queries on every load and feeds the results in, exactly as it does inside the console (see Data model). The embed is never a frozen image or a one-time export. Change the underlying data and the embed reflects it the next time someone opens the host page.

It is also read-onlyby construction. The embedded Page has no callbacks, no session, and no way to write — it renders and nothing else.

The signed embed token

Every embed carries a signed embed token in the iframe URL. The token is what makes the surface safe to expose publicly: it is minted by someone who already has access, it encodes the exact data scope the embed is allowed to render at, and it expires. The host validates the token on every fetch before it renders a single row.

Tokens are signed with a workspace signing secret you manage in Settings → Developer → Embedding. Keep at least one secret active to mint tokens; revoking a secret instantly invalidates every token it ever signed, so it doubles as a kill switch if an embed URL leaks.

The mint flow

You don’t hand-build the token or the URL. Open the Page, click Embed in the header, choose an audience, and the console mints a token and hands you a ready-to-paste snippet:

<iframe
  src="https://console.amdahl.co/embed-page/<workspace-slug>/<page-id>?t=<token>"
  style="width:100%;border:0"
  loading="lazy"
></iframe>

The same mint is available over the API for automation: POST /api/platform/v1/pages/:id/embed-token with an audience (and optional ttl_seconds, rules, and an origins allowlist) returns the token, its expires_at, and the ready embed_url. Tenancy comes from the API key (see Using the API), the same as the rest of the Page lifecycle (Authoring via the API).

Fail closed: the security invariant

The public embed endpoints fail closed. A request with a missing, malformed, expired, or revoked token renders nothing— not a partial Page, not an error that leaks whether the Page exists, just an unavailable state. The token is the only gate, and the default with no valid token is to show nothing.

• No token, no data. The definition and render endpoints both require a valid token before they return anything.
• Scope is baked into the token. An embed can never render more than the token authorized, no matter what the host page asks for.
• Revoke is immediate. Revoking the signing secret invalidates outstanding tokens on their next load.

Pin where it can be framed: frame-ancestors

You can pin which sites are allowed to frame an embed by passing an origins allowlist when you mint the token. The host serves the embed with a frame-ancestorscontent-security-policy directive built from that list, so a browser refuses to render the iframe on any origin you didn’t name. Leave it open to embed anywhere, or lock it to your own domains so a leaked URL can’t be reframed on a site you don’t control.

Audience: self vs workspace vs public

The audience you choose at mint time decides whose data scope the embed renders at. There are three:

• Only me (self). The embed renders scoped to yourown data access — the same numbers you’d see opening the Page yourself. Good for a private dashboard you embed in a tool only you use.
• My workspace (workspace).The embed renders at the workspace’s full data scope, so every viewer sees the same numbers regardless of who they are. Good for an internal wiki where everyone is already a teammate.
• Public (public). The embed renders with no tenant data scope and can be opened by anyone with the link. This is the only audience an unauthenticatedviewer can use — and because it puts data in front of the open internet, it requires a workspace admin to mint. Non-admins can mint self and workspace embeds; only an admin can mint a public one.

Agent vs user: the same mint, clamped to the principal

An agent embeds a Page exactly the way a person does — the same mint endpoint, the same audiences. There is no separate, looser agent path. The token is always clamped to the minting principal: a token minted by an agent can never render at a wider scope than that agent already has, just as a user’s token can never exceed the user’s own access. So letting an agent generate an embed is safe by construction — it cannot mint itself more reach than it was granted, and a public embed still needs the admin gate no matter who (or what) asks for it.

Managing signing secrets

Signing secrets live in Settings → Developer → Embedding, admin-only. Create one and the plaintext value is shown exactly once— copy it into your signing service then; it is never recoverable afterward. List shows only a non-sensitive prefix and a last-used time. Revoke a secret to retire it and invalidate every token it signed. Keep this surface tight: a signing secret can mint embed tokens for the workspace, so treat it like a password.

Where to go next

• Data model— how a Page declares the queries the embed runs live, scoped per token.
• Access— how page-level grants and per-viewer data scope compose inside the console (the in-app counterpart to the embed token’s clamp).
• Authoring via the API— the REST Page lifecycle the mint endpoint sits alongside.