Embed a report

You can show a report on another website in two ways. A public link lets anyone view the report without signing in. A secure embed lets your own server decide who sees the report, and supports row-level security.

Before you start

• The report must be published. Otherwise the dialog shows Publish the report before embedding it.
• You need Build and the share permission on the report. Workspace Admin and Editor have both. See Sharing.
• A public link also needs the organization switch Allow publish to web. It is off by default.
• A secure embed needs the organization switch Allow authenticated embedding and an app token, which only a workspace Admin can create.
• A report in My workspace cannot be embedded. Move it to a shared workspace first.

Choose public or secure

	Public website (iframe)	Secure embed (app token)
Who can view	Anyone with the link, without signing in.	Only the people your server lets in.
Row-level security	Not allowed.	Supported.
Set up	Copy a link or HTML snippet.	Your server gets a short-lived embed token.
Use for	Public data only.	Customer portals, internal sites.

Public embed

1. Open the report in the viewer.
2. Click … › Embed. The Embed report dialog opens.
3. Pick Public website (iframe).
4. Read the warning The data becomes public, then tick I understand the data becomes public.
5. Click Create public link.
6. Copy the Link, or the HTML to paste into your website, with Copy.

Caution

The link and HTML are shown once. Copy them now. Later you can only make a new one with Rotate. Anyone with the link or code can see the report and the data it shows, including people outside your organization. Do not use it for sensitive data.

Manage public links: the Public links list shows each link as Active or Revoked.

• Rotate makes a new link and revokes the old one at once.
• Revoke stops the link at once. Pages that embed it stop showing the report.

A public link cannot be created when:

• the organization has turned off Allow publish to web;
• the data model of the report has row-level security;
• the report already has 5 active public links.

Secure embed

A secure embed has three parts:

1. An app token of the workspace, kept on your server.
2. Your server trades the app token for a short-lived embed token by calling POST /api/embed/token.
3. Your web page loads the report in an iframe and hands it the embed token with postMessage. The token never goes in a URL.

Create an app token

1. In the left menu, under Workspace, open App tokens.
2. Click New app token.
3. Type a Name (up to 100 characters).
4. Pick the Scope: All reports in the workspace, or Chosen reports (up to 100).
5. Pick Expires after: 30, 90, 180 or 365 days. The default is 90.
6. Optionally fill in Allowed websites (optional): one origin per line, for example https://portal.example.com, up to 20. Leave it empty to allow any website.
7. Confirm. Copy the secret.

Caution

The secret is shown once. Keep it on your server; never send it to a browser.

The list shows Name, Scope, Expires, Last used, Status and Actions. Rotate makes a new secret and revokes the old one at once. Revoke stops the token and every embed token made from it. Tick Show revoked tokens to see old tokens. A workspace can have up to 20 active app tokens. Every action is audited.

Embed the report

1. Open the report in the viewer and click … › Embed.
2. Pick Secure embed (app token).
3. Use the two samples, Server (get an embed token) and Web page (iframe), as a starting point for your developers.
4. Click Open workspace App tokens if you still need a token.

An embed token lasts from 1 to 60 minutes; the default is 60. When the report’s data model has row-level security, your server must send the viewer’s identity: a user name and up to 16 role names. See Row-level security.

What an embedded report can do

An embedded report shows its pages, slicers and cross-highlight. It does not offer drill, drill-through, focus mode, the phone layout or Realtime auto refresh.

Messages a visitor may see:

Message	Meaning
This embed link is not valid or was revoked.	The link was revoked or rotated.
The embed session has expired.	The embed token ran out. Your page must ask your server for a new one.
The organization turned public sharing off.	Allow publish to web was turned off.
This website may not show the report.	The website is not in the app token’s Allowed websites.
This report cannot be viewed publicly.	The data model has row-level security.

Turn public embed on or off (admins)

An organization Owner or Admin controls Allow publish to web in Organization settings › Embed. Turning it off stops every public link of the organization at once. Secure embeds are controlled by their own switch, Allow authenticated embedding, in the same place. See Embedding and appearance settings.

Notes

• Every public link and app token action is recorded in the audit log.
• Revoked links and tokens cannot be turned back on. Create new ones.

FAQ

Can I embed a report that uses row-level security? Yes, with a secure embed. Public links are not allowed for such reports.

I lost the public link. Can I see it again? No. Click Rotate to make a new one, then update your website.

Who can create app tokens? Only workspace Admins: “Only workspace admins manage app tokens.”