Skip to main content

Embed payload reference

This reference covers every parameter you can use when embedding. The embed payload is the signed JSON your backend turns into a token. It describes what to show, who is viewing, and what they can see and do. A handful of unsigned URL parameters adjust the UI on top of that.

If you're embedding for the first time, start with the Quickstart. Come back here when you need the full list.

How parameters work:

How embed payload and URL parameters work
  • payload-code → jwt-sign-payload
  • jwt-sign → embed-token-value
  • embed-token-value → embed-url-token
  • embed-url-token → payload-params
  • embed-url-path → url-params
  • embed-url-panel → url-params
Payload parametersURL parameters
LocationSigned JWT tokenAppended to the embed URL
PurposeContent, security, permissions, data access (which dashboards to show, row-level rules, export rights)UI, navigation, display preferences (expand the navigation panel, deep-link to a dashboard, pre-fill a filter)
User modifiableNoYes

Payload parameters (JWT-signed)​

Payload parameters are included in the JWT your backend signs with your embed Secret. Because they're cryptographically signed, viewers can't change them, which makes them the right place for anything that affects content, identity, or data access.

Embedded objects​

Every payload says what to embed: either a list of dashboards and datasets, or the name of a persisted Embed Portal. It also sets when the token expires.

ParameterTypeDescriptionRequired
objects.dashboardsarrayDashboards to embed, as a list of unique names.Yes, unless using embed_portal
objects.datasetsarrayDatasets to embed, by unique name. Adding a dataset unlocks exploration, drill-down, and view underlying data on it, and lets Ask AI query it.No
embed_portalstringName of a persisted Embed Portal. Use instead of objects when your embedded content is defined as code in Holistics.Yes, unless using objects
expnumberToken expiration as a Unix timestamp (e.g., 1769502969). The token is rejected after this time.Recommended

Example: inline objects

const payload = {
  objects: {
    dashboards: ["sales_overview", "revenue_trends"],
    datasets: ["ecommerce"],
  },
  exp: Math.floor(Date.now() / 1000) + 3600, // Expires in 1 hour
};

Example: persisted Embed Portal

const payload = {
  embed_portal: "customer_portal",
  exp: Math.floor(Date.now() / 1000) + 3600,
};
One source of objects

Use either embed_portal or objects, not both. A payload that sets both is rejected, so it's always clear where the embedded content comes from.

Finding unique names

Dashboards and datasets are referenced by the unique name declared in AML (the name after Dashboard or Dataset), not by their display title. The Embedded Analytics Sandbox on the Embedded Analytics page shows the exact names and generates a payload for you.

User identity​

These parameters identify who's viewing. They unlock personal features like saving dashboards, email subscriptions, and organization workspaces, and they let Holistics attribute activity to a user in logs.

ParameterTypeDescriptionRequired
embed_user_idstringUnique identifier for the user in your system. See Identity & Workspace.For user-built dashboards and email subscriptions
embed_org_idstringUnique identifier for the user's organization. See Identity & Workspace.For organization workspaces
embed_user_emailstringUser's email address for email subscriptionsFor email subscriptions

Example:

const payload = {
  // ... embedded objects
  embed_user_id: "user_123",
  embed_org_id: "org_456",
  embed_user_email: "[email protected]",
};

Data access​

Control which rows each viewer can see. There are two ways to express row-level permissions, and you can use both at once. When both apply, they are combined with AND, so the payload can only narrow access, never widen it.

ParameterTypeDescriptionRequired
permissions.row_basedarrayDirect row-level permissions written in the payload. Each rule has a path (dataset, model, field), an operator, values, and an optional modifier. See Direct permissions.If restricting data without dataset rules
user_attributesobjectKey-value pairs matched by attribute-based row-level permissions defined in your datasets. Values must be arrays (e.g., region: ['US']). Also used by dynamic data sources, localization, and as Ask AI context.If using dataset rules, dynamic data sources, or Ask AI

Example:

const payload = {
  // ... embedded objects and user identity
  permissions: {
    row_based: [
      {
        path: { dataset: "ecommerce", model: "companies", field: "id" },
        operator: "is",
        values: [42],
      },
    ],
  },
  user_attributes: {
    region: ["US", "EU"],
    company_id: [42],
  },
};

Settings​

Configure what viewers can do with the data and how dashboards are displayed. Settings apply to every dashboard in the embed.

ParameterTypeDescriptionDefault
settings.allow_dashboard_exportbooleanAllow users to export dashboards (PDF, PNG)false
settings.allow_raw_data_exportbooleanAllow raw data export (CSV, Excel)false
settings.allow_data_subscribebooleanEnable email subscriptions. Requires embed_user_id, embed_user_email, and allow_dashboard_export.false
settings.ai.enabledbooleanEnable Ask AI. Requires at least one dataset in objects.datasets or the portal.false
settings.default_timezonestringTimezone for data display (e.g., "UTC", "America/New_York"). See Timezone settings.Workspace default
settings.allow_dashboard_timezone_changebooleanAllow users to change the current dashboard's timezonetrue
settings.hide_header_panelbooleanHide the dashboard header panel (title and actions), for example when your app already shows a headingfalse
settings.hide_dashboard_filters_controls_panelbooleanHide the dashboard filter and control panel. Combine with default filter values or embed events if your app drives the filters itself.false
settings.dashboard_autorun_on_changesbooleanRe-run the dashboard automatically whenever filters or controls change, without clicking Apply. Overrides the dashboard's own auto-run on changes setting. Every change fires queries, so leave it off for heavy dashboards.false

Example:

const payload = {
  // ... embedded objects and user identity
  settings: {
    default_timezone: "America/New_York",
    ai: { enabled: true },
    allow_dashboard_export: true,
    allow_raw_data_export: false,
    allow_data_subscribe: true,
    allow_dashboard_timezone_change: true,
    hide_header_panel: false,
    hide_dashboard_filters_controls_panel: false,
    dashboard_autorun_on_changes: true,
  },
};

Workspace permissions​

Define whether the viewer can save their own dashboards and collaborate with their organization. These require embed_user_id (and embed_org_id for the organization workspace).

ParameterTypeDescriptionDefault
permissions.enable_personal_workspacebooleanAllow the user to save dashboards to a personal workspacefalse
permissions.org_workspace_rolestringThe user's role in the organization workspace: 'no_access', 'viewer', 'editor''no_access'

Example:

const payload = {
  // ... embedded objects and user identity
  permissions: {
    enable_personal_workspace: true,
    org_workspace_role: "editor", // Options: 'no_access', 'viewer', 'editor'
  },
};

Full payload example​

Here's a complete example combining every section:

const payload = {
  // What to embed
  objects: {
    dashboards: ["sales_overview", "revenue_trends"],
    datasets: ["ecommerce"],
  },

  // Who is viewing
  embed_user_id: "user_123",
  embed_org_id: "org_456",
  embed_user_email: "[email protected]",

  // What data they can see
  user_attributes: {
    region: ["US", "EU"],
    company_id: [42],
  },

  // What they can do
  permissions: {
    enable_personal_workspace: true,
    org_workspace_role: "editor",
  },
  settings: {
    default_timezone: "America/New_York",
    ai: { enabled: true },
    allow_dashboard_export: true,
    allow_raw_data_export: false,
    allow_data_subscribe: true,
    dashboard_autorun_on_changes: true,
  },

  // Token expiration (Unix timestamp)
  exp: Math.floor(Date.now() / 1000) + 3600, // Expires in 1 hour
};

// Generate JWT token
const embedSecret = "YOUR_EMBED_SECRET"; // Replace with your Secret from Holistics
const token = jwt.sign(payload, embedSecret, { algorithm: "HS256" });

Production checklist​

The payload structure is standard, but some values must match your Holistics setup and your own user model. Check these before signing the token and building the embed URL:

  • objects.dashboards and objects.datasets use unique names from AML, not display titles. If you use embed_portal, the name must match a published Embed Portal.
  • Every payload that serves more than one customer carries row-level permissions, through permissions.row_based, user_attributes, or both.
  • user_attributes keys match the attributes used by your dataset permission rules. You can manage user attributes programmatically with the User Attributes API and User Attribute Entries API.
  • embed_user_id and embed_org_id are stable identifiers from your own application.
  • The embed URL uses the correct regional or custom domain and your Key ID.
  • Feature flags such as AI, subscriptions, exports, and workspace permissions match your product and security policy.
  • exp is set, ideally 24 hours or less.

URL parameters (not signed)​

URL parameters customize the UI without regenerating tokens. Use them to control navigation panel state, deep-link to a specific dashboard, or pre-fill a filter. They don't affect security or data access, so viewers can safely change them (which also makes them good for bookmarks and shared links).

URL structure​

Your embed URL must use the domain of your Holistics data center. Holistics has three regional app domains: APAC uses secure.holistics.io, US uses us.holistics.io, and EU uses eu.holistics.io. If you're not sure which one your account uses, see Data Centers. If you use a custom domain, replace the full host with it.

App domain

https://secure.holistics.io/embed/{embed_key_id}/{initial_object}?_token={token}&{query_params}
                                  └──────┬─────┘ └──────┬───────┘        └──┬──┘ └─────┬─────┘
                                     Key ID       Path (optional)        Token    Query params
ComponentDescription
{embed_key_id}Your Key ID from the Embedded Analytics page. The same one for every embed.
{initial_object}Optional path to control which page opens first
{query_params}Optional query parameters for UI customization (see Query parameters)

Initial object (URL path)​

Deep-link viewers straight to the content they need: a specific dashboard, a dataset, or the Ask AI page. This lets you build targeted links from emails, notifications, or your own navigation.

Supported paths:

  • /objects/<object_name>: open a specific dashboard or dataset
  • /ai: open the Ask AI page (requires settings.ai.enabled: true)
  • (empty): use the default (see resolution order below)

Examples:

  • Dashboard: https://{region_domain}.holistics.io/embed/abc123/objects/sales_dashboard?_token=...
  • Ask AI: https://{region_domain}.holistics.io/embed/abc123/ai?_token=...

Replace {region_domain} with secure, us, or eu.

Resolution order:

  1. URL path, if specified and the object is in the payload
  2. initial_object in the Embed Portal definition, if you're using one
  3. The first dashboard in objects.dashboards (or in the portal's objects)

Query parameters​

Fine-tune the UI with query parameters appended to the embed URL.

ParameterValuesDefaultDescription
left_panel_stateexpanded, collapsedcollapsedControls the left navigation panel's expand/collapse state. The panel only appears when the embed has more than one dashboard, dataset, or workspace.
{filter_block_uname}Any valid filter valuenonePre-fill a filter on the dashboard the URL opens to, using is / equal to / matches-style conditions. See Default filter values below, and Passing filter parameters via URL for syntax and Supported operators.

Default filter values​

Default filter values set the filters a dashboard opens with. They're useful for showing contextual data on load: a user clicks "Europe" in your app, so the region filter starts on Europe. You set them through URL query parameters, not in the signed payload.

Add each filter's unique name as a query parameter on the embed URL, with the value to apply:

https://{region_domain}.holistics.io/embed/{embed_key_id}/objects/sales_dashboard?_token=...&region_filter=Europe

The values apply to the dashboard the URL opens to. Query parameters support is, equal to, and matches-style conditions only: relative dates (such as "last 6 months") and other custom operators aren't supported. For those, change the filter with embed events once the dashboard loads. See Passing filter parameters via URL for the full syntax and Supported operators.

Not a data security feature

Default filter values only set the starting state. URL parameters aren't signed, so viewers can change them, and they can change the filter in the dashboard too. To restrict what data a viewer can see, use row-level permissions. See Enforcing data access control for the difference.

URL examples​

Common ways to combine paths and query parameters:

Use caseURL
Basic embedhttps://{region_domain}.holistics.io/embed/abc123?_token=...
Open a specific dashboardhttps://{region_domain}.holistics.io/embed/abc123/objects/sales_dashboard?_token=...
Open the Ask AI pagehttps://{region_domain}.holistics.io/embed/abc123/ai?_token=...
Expanded navigation panelhttps://{region_domain}.holistics.io/embed/abc123?_token=...&left_panel_state=expanded
Open a dashboard pre-filteredhttps://{region_domain}.holistics.io/embed/abc123/objects/sales_dashboard?_token=...&region=US

If you embedded a dashboard before the new embed payload, your setup uses a per-dashboard embed code and secret, with filters, permissions, settings, and drillthroughs at the top level of the payload. Those links keep working, and Legacy single-dashboard embedding documents them. To adopt the parameters on this page (multiple dashboards, datasets, identity, Ask AI), switch to your shared embed credentials and move the dashboard into objects.dashboards. The migration guide covers this step by step.

Open Markdown
Let us know what you think about this document :)