Embedding private objects

Written by

Updated at August 25, 2025

How to embed a private object
Updating a token without losing your filter states
Unsigned parameters
Signed parameters
Recommendations
Things to consider when embedding dashboards

Note

This feature is only available with the Business service plan.

You can securely embed private charts or dashboards into a website or app using special JWT token links.

Embedding private objects only works in the new DataLens object model at the workbook level and is only available to the workbook administrator.

You cannot embed private objects based on the following connections:

Snowflake
Metrica
AppMetrica
Yandex Cloud Billing
DataLens Usage Analytics

Note

You can share a dashboard or chart based on Yandex Metrica or AppMetrica data.

How to embed a private object

Create a key for embedding:

Note

You can use one key to embed multiple objects.
1. Go to the DataLens home page.
2. In the left-hand panel, select Collections and workbooks.
3. Open the workbook with the object you want to embed.
4. At the top of the screen, click and select Keys for embedding.
5. In the window that opens:
  1. Click Create key.
  2. Enter the key name and click Create.
  3. At the bottom, click Download key file or copy the key value.
    
    Warning
    
    After you close the window, all data from it will be lost.
    
    The new key for embedding will appear in the list.
Configure the embedding for a private object:

Note

You can configure multiple embeddings for each object.
1. In the row with the object, click and select Embedding settings.
2. In the window that opens, click New embedding.
3. In the settings window, specify:
  For a chart
  
  For a dashboard
  - Name: Enter a name for the embedding.
  - Key: Select a previously created key for embedding.
  - Select Default parameters:
    
    Enable all (default): All the unsigned parameters are enabled, unless explicitly disabled.
    
    Disable all: All the unsigned parameters are disabled, unless explicitly enabled.
    
    These restrictions do not apply to signed parameters from the token.
  - (Optional) Disabled parameters: Specify the names of unsigned parameters you want disabled when embedding a chart. Available in Enable all mode.
  - (Optional) Enabled parameters: Specify the names of unsigned parameters that can be provided in the embedding link. Any parameters not specified in the list will be ignored when attempting to provide them in the embedding link. Available in Disable all mode.
  - (Optional) Allow data export: Enable the display of the menu that allows you to export the chart data. To export data, click → Save as in the top-right corner of the chart and select the format: XLSX, CSV, or Markdown.
  - Name: Enter a name for the embedding.
  - Key: Select a previously created key for embedding.
  - (Optional) Disabled parameters: Specify the names of unsigned parameters you want disabled when embedding a dashboard. These restrictions do not apply to signed parameters from the token. By default, you can provide any parameters in the embedding link. If they are specified in the dashboard settings, they can affect charts and selectors.
    
    Note
    
    If there are selectors with restricted parameters on the dashboard, those will not be available when embedding.
  - (Optional) Allow data export: Enable the display of the menu that allows you to export the chart data. To export data, click → Save as in the top-right corner of the chart and select the format: XLSX, CSV, or Markdown.
4. Click Create. In the ID column, copy the ID of the object to embed, and then click Close.

Create a token:

Prepare a payload for the token, i.e., information about the object to embed. The payload contains the following fields:
- embedId: ID of the object to embed.
- iat: JWT issue time in Unix Timestamp format.
- exp: Token expiration time in Unix Timestamp format.
  
  Warning
  
  Tokens with more than 10 hours between exp and iat are invalid.
- dlEmbedService: Service ID string constant, YC_DATALENS_EMBEDDING_SERVICE_MARK.
- (Optional) params: Signed chart parameters provided as part of the token. They cannot be changed without regenerating the token.
  Warning
  - The generated token is transmitted as part of the network request header, so its maximum size is limited to 30 KB. Keep this in mind when using signed parameters.
  - For correct operation, use only a string or an array of strings as parameter values.
  Here is an example:
```
{
  "embedId": "ieez7********",
  "iat": 1516239022,
  "exp": 1516240822,
  "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}
```

To create a JWT token, sign the prepared payload with the private key you got earlier when creating the key for embedding.

Note

Use the PS256 algorithm when creating the JWT.

To create a JWT token, use these code samples:

Python

Node.js

Install cryptography for working with PS256:

pip3 install cryptography

Run the following code:

import time
import jwt
import json

private_key = b"""<private_key>"""

now = int(time.time())
payload = {
   'embedId': "<embed_object_ID>",
   'dlEmbedService': "YC_DATALENS_EMBEDDING_SERVICE_MARK",
   'iat': now,
   'exp': now + 360,
   "params": {  }}
   
# JWT generation.
encoded_token = jwt.encode(
   payload,
   private_key,
   algorithm='PS256',
   )

print(encoded_token)

Install the jsonwebtoken package using npm:

npm install jsonwebtoken

Run the following code:

const privateKey = `<private_key>`;

const now = Math.floor(Date.now() / 1000);
const payload = {
embedId: '<embed_object_ID>',
dlEmbedService: 'YC_DATALENS_EMBEDDING_SERVICE_MARK',
iat: now,
exp: now + 360,
params: {},
};

const jwt = require('jsonwebtoken');

const encodedToken = jwt.sign(payload, privateKey, {
algorithm: 'PS256',
});

console.log(encodedToken);

Install the jwt-go package:

go install github.com/golang-jwt/jwt/v5@latest

Run the following code:


package main

import (
  "fmt"
  "time"

  "github.com/golang-jwt/jwt/v5"
)

func main() {
  privateKey, err := jwt.ParseRSAPrivateKeyFromPEM([]byte(`<private_key>`))

  now := time.Now().Unix()
  payload := jwt.MapClaims{
      "embedId":        "<embed_object_ID>",
      "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK",
      "iat":            now,
      "exp":            now + 360,
      "params":         map[string]interface{}{},
  }

  token := jwt.NewWithClaims(jwt.SigningMethodPS256, payload)
  signedToken, err := token.SignedString(privateKey)
  if err != nil {
      fmt.Println("Error generating token:", err)
      return
  }

  fmt.Println(signedToken)
}

Generate an embedding link:

For a chart

For a dashboard

https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<token>

Where <token> is the JWT.

https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<token>

Where <token> is the JWT.

Add an embedding link to your website or app, e.g.:
For a chart

For a dashboard
```
<iframe src="https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
```
Where:
- src: Embedding URL.
- <token>: JWT.
- width: Chart width.
- height: Chart height.
- frameborder: Chart border (yes or no).
```
<iframe src="https://datalens.yandex.cloud/embeds/dash#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
```
Where:
- src: Embedding URL.
- <token>: JWT.
- width: Dashboard width.
- height: Dashboard height.
- frameborder: Dashboard border (yes or no).

Updating a token without losing your filter states

Replacing a JWT in an embedding link resets filters on the embedded dashboard to their default values.

To update the embedding link without losing filter states, use the postMessage method.

To update a JWT in a link, send an object of the following type to iframe using the postMessage method:

{
    type: 'SECURE_EMBEDDING_TOKEN_UPDATE',
    token: <updated_token>
}

Where <updated_token> is your updated JWT.

As a result, queries from your dashboard or chart will be signed with the new token. The dashboard or chart will automatically get updated if you changed the signed parameters in your new token.

Here is an example:

const iframe = document.getElementById('ID_IFRAME');

iframe.contentWindow.postMessage({
    type: 'SECURE_EMBEDDING_TOKEN_UPDATE',
    token: 'NEW_TOKEN'
}, 'https://datalens.yandex.cloud/');

When updating a token, keep in mind its expiration time.

By default, any parameters, except those explicitly disabled, can be provided in the embedding link. They should be specified in the URL before the token hash. This allows you to change some widget/dashboard parameters on the client side without recreating the token.

For example, where a chart or dashboard employs the from and/or to parameters to filter values by time, you can provide these parameters in the embedding link before the token hash:

For a chart

For a dashboard

<iframe src="https://datalens.yandex.cloud/embeds/chart?from=2022-01-01&to=2023-02-05#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>

Where:

src: Embedding URL.
<token>: JWT.
from=2022-01-01&to=2023-02-05: Unsigned parameters.

<iframe src="https://datalens.yandex.cloud/embeds/dash?from=2022-01-01&to=2023-02-05#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>

Where:

src: Embedding URL.
<token>: JWT.
from=2022-01-01&to=2023-02-05: Unsigned parameters.

In the embedding link, any unsigned parameters are ignored if:

For a chart

For a dashboard

The parameter is listed among the parameters disabled in Enable all mode.
The parameter is not listed among the parameters enabled in Disable all mode.

The parameter names are in the list of disabled parameters.

Signed parameters

Signed parameters are provided as part of the token. They cannot be changed without regenerating the token. For correct operation, use only a string or an array of strings as parameter values.

Embedding settings for enabled and disabled parameters do not apply to signed parameters. They will be provided to charts and selectors in any case.

By default, signed parameter values are overridden by external parameters with the same name. The selector parameter, dashboard setting parameter, or link parameter will take priority over the signed ones.

You can dynamically update signed parameters by refreshing a token without losing filter states.

Warning

Starting August 26, 2025, the behavior of signed parameters will change.

Features of the new behavior:

Values of signed parameters will take priority. If both a signed parameter and external parameter with the same name are provided to a widget at the same time, the signed one will apply.
Selectors by signed parameters will not affect dashboard charts.

Signed parameters provide more secure access to data: users with access to embedded objects will not be able to change these parameters. You can use signed parameters to filter charts and provide a specific user with only the slice of data they need.

Recommendations

When embedding private objects, follow these guidelines:

Default values should be provided in the link parameters.
Note that any parameter in the link will override any signed parameter with the same name.
To block changes to a parameter value:
For a chart

For a dashboard
1. Add a signed parameter with a required value into the token.
2. In chart embedding settings:
  - In Enable all mode, add the parameter to the disabled list.
  - In Disable all mode, do not add the parameter to the enabled list.
1. Add a signed parameter with a required value into the token.
2. In the dashboard embedding settings, add the parameter to the disabled list.
Warning

Starting August 26, 2025, the behavior of signed parameters will change. Signed parameters will become immutable by default; you will no longer need to create lists of enabled or disabled parameters.

Things to consider when embedding dashboards

When embedding dashboards, consider the following:

Embedded dashboards can only be opened in view mode. Their navigation bar and, by default, the menu for charts are hidden. Enable Allow data export in embedding settings for your charts to display the menu, which allows exporting the chart data.
When you open a dashboard, its settings apply.
For unsigned parameters to work correctly, specify them in the dashboard settings.
Unsigned parameters work in the same way as regular parameters in a dashboard link.
You cannot provide the state of filtered charts in the state parameter.
The embedding link may not contain a dashboard header.
In the embedding link, use tab to specify the tab to open the dashboard on.

Embedding private objects

How to embed a private objectHow to embed a private object

Updating a token without losing your filter statesUpdating a token without losing your filter states

Unsigned parametersUnsigned parameters

Signed parametersSigned parameters

RecommendationsRecommendations

Things to consider when embedding dashboardsThings to consider when embedding dashboards

Was the article helpful?

How to embed a private object

Updating a token without losing your filter states

Unsigned parameters

Signed parameters

Recommendations

Things to consider when embedding dashboards