Security for embedded analytics

Embedded analytics puts your data inside someone else's browser, so a few mechanisms work together to keep each viewer limited to what they're allowed to see. This page explains each one and what you need to do on your side.

HTTPS

Holistics only allows embedding on pages served over HTTPS. This is enforced by a Content Security Policy (CSP) rule, and it keeps embed tokens from being intercepted in transit. If you see a blank iframe during local development, see the FAQs for how to run your local site over HTTPS.

Secret key

The Secret you generate on the Embedded Analytics page signs your embed payload with HMAC-SHA256 (HS256). When Holistics receives a token, it recomputes the signature with the same Secret. If anyone has changed the payload, the signatures don't match and the token is rejected.

Keep the Secret on your backend and never send it to the browser.

Authentication

Holistics authenticates each embed request with a signed JSON Web Token (JWT) instead of a user login.

Mechanism

How embedded analytics works

• 1. Embed credential
• 3. Frontend
• 2. Backend
• iframe-box — The path carries the Key ID from your shared credential. There is no per-dashboard embed code.
• [HTML node]
• embed_key_id — The Key ID from your shared embed credential.
• [HTML node]
• token — The signed JWT your back end just produced.
• [HTML node]
• [HTML node]
• Payload — One payload describes what to show, who is viewing, and what they may do.
• Content: Dashboards, Datasets
• Permissions
• User settings
• and more
• jwt-box — Sign the payload with the Secret from your shared embed credential.
• JWT.encode(
• payload
• ,
• secret_key
• , 'HS256')
• token — A short-lived JWT. It goes in the embed URL as _token.
• Key ID
• Secret

• payload-box → chip-payload
• jwt-box → token-box
• token-box → chip-token
• node-2 → chip-secret
• node-1 → chip-key

• On the frontend, the Holistics dashboard is embedded in your website or application with an iframe. The iframe URL contains your embed Key ID and a token that defines what the viewer can see and do.
• The token is a JWT built from a payload that lists the dashboards to show, the viewer's identity, permissions, settings, and an expiry time, signed with the Secret you got when you generated embed credentials.
• Holistics uses the token to identify the viewer and show the dashboard with only that viewer's data.

Why JSON Web Token (JWT)?

Embedded analytics is designed for multi-tenancy: you embed dashboards in your own application, and each of your users sees different data depending on their permissions.

A signed token lets you identify your users and make sure they only see the data they're allowed to. Viewers can't pull other data by changing URL parameters, because their permissions are part of the token. They also can't edit the token, because Holistics verifies its signature and rejects tampered tokens.

Token expiration

Every token must have an expiry time (exp). We recommend 24 hours or less.

Expiry limits the damage if a token is stolen. Anyone who has a viewer's token can use it to act as that viewer until it expires, so a short expiry keeps that window small.

Sensitive data

The payload is signed, not encrypted. Signing stops anyone from changing the payload, but anyone who has the token can decode it and read its contents.

danger

Don't put passwords, API keys, or other sensitive data in the payload. Only include user details that the viewer is already allowed to see.

Enforcing data access control the right way

Row-level permissions and default filter values can both narrow what a dashboard shows, but only row-level permissions restrict access. They're part of the signed token and are enforced on every query at the dataset level, so viewers can't get around them. Default filter values are set through unsigned URL parameters and only set the filter a dashboard opens with: viewers can change them to anything. Use default filter values for convenience and row-level permissions for security. See Row-level permissions to set them up.