As an added service, Chartio provides the ability to embed dashboards into existing web applications.

This powerful feature allows you to provide personalized analytics to your customers, increasing the overall value of your product offering with minimal development effort.

If you're interested in seeing a demo or enabling this for your account, please contact sales@chartio.com.


Integrating embedded dashboards into your application involves two open, simple, and easy-to-use technologies: JSON web tokens (JWT) and HTML iframes.

JWTs allow you to, in a tamper-proof manner from your end user's perspective, pass Chartio the dashboard id you would like to embed as well as the values to apply to any dashboard variables. These values can be controlled by your application's native UI elements to provide robust filtering capabilities.

HTML iframes are a common technology used for embedding third party widgets in a webpage.

Plugging everything together is as simple as placing an iframe in your HTML that references in its src attribute a Chartio endpoint appended with a JWT.

Embedding a Dashboard

The following sections use Python as an example. For other examples, see retreiving example code.

Create or Use an Existing Dashboard

Using the same Chartio interface you're used to, add a dashboard or pick an existing dashboard to be embedded.

Parameterize your Dashboard

Use hidden dashboard variables to parameterize charts on the dashboard. Upon embedding the dashboard, we will filter the data being displayed by passing values to these hidden variables via a JWT.

Retrieve dashboard example code

From the dashboard's sidebar, select Settings, then click the Embed button to retrieve the dashboard example code. Keep this handy as we will refer to it in the next step.

Retrieve Embed Secret

From the top navigation, select the ellipsis menu and choose Embedding. You'll see your Embed Secret. Keep this handy as we will refer to it in the next step. You'll need Owner access to view the Embed Secret.

Install a Third Party JWT Library

JWTs can be generated by following the procedure here however using a third party library is recommended to reduce the chance for error.

pip install python-jwt

Construct a Payload

Construct a payload using as a reference the previously retrieved dashboard example code.

A payload should include the following:

  • organization: Your Chartio organization id.
  • dashboard: The id of the dashboard to be embedded.
  • env: A mapping of variable names to values which will be passed to the hidden variables on the dashboard.
  • exp: (Optional) An expiration value that specifies when the token expires.
  • Any additional values required by the third party JWT library of your choice (e.g. iat). See the example code for Ruby and Javascript.


payload = {
    'organization': 16417,
    'dashboard': 38727,
    'env': {
        'ACCT_ID': '1', 
        'DATE_RANGE': [
        'USER_ID': '1'

The values included in the env mapping can be sourced from forms that are submitted to your web application. This allows the embedded dashboard to be filtered based on UI elements native to your application, providing a familiar interface for your end users. Additionally, it allows UI elements vastly different from what Chartio natively offers to be used. Below is an example of pulling the env values from a Django form object as well as adding an env value based on session data that is unmodifiable by the end user (ACCT_ID).

env = {k.upper(): str(v) for k, v in form.cleaned_data.items()}
env['ACCT_ID'] = request.session['ACCT_ID']
payload = {
    'organization': 16417,
    'dashboard': 38727,
    'env': env

Wrap the Payload in a JWT

Generate a JWT with the payload as the body using your organization secret and the HMAC256 signature mechanism.

token = jwt.generate_jwt(payload, ORGANIZATION_SECRET, 'HS256',
                         datetime.timedelta(days=1)) # expires in 1 day

Submit the JWT to Chartio in an iframe

Insert an iframe element into your HTML with a src url consisting of the generated JWT appended to the base url from the dashboard example code.

BASE_URL = 'https://embed.chartio.com/d/38727'
print '<iframe src="%s/%s"></iframe>' % (BASE_URL, token)

Test the Results

Test the results by requesting the application page with the embedded iframe. A "Loading" message should appear each time an embedding request includes a brand new JWT. The dashboard will be cached on Chartio's servers for all subsequent requests until the JWT expires.

Optimizing Database Load


Queries relating to an embedded dashboard are only run when the iframe src url is requested with a brand new JWT. The results are cached for all subsequent requests until the JWT expires allowing an opportunity to pre-populate a cache with common iframe src urls by requesting them server side before end users ever request the urls. This will eliminate any loading time end users would have had to endure waiting for the queries to complete. This is not required however, and the mechanism you choose to build this cache is entirely up to you (e.g. lazy load, batch job, etc.).

Usage Statistics

On the embedding settings page, organization owners can see the number of times each dashboard has been embedded. This number corresponds to the number of times a dashboard has been requested for embedding with a completely new JWT and represents the number of times the queries associated with a dashboard have been sent to your database. If this number seems high, you may want to look into caching to avoid unnecessary load on your database.


Organization Secret

Your organization secret is used during the JWT generation to secure the JWT from tampering using the HMAC256 signature mechanism. The secret is unique for your organization and needs to be kept secret to assure that embedding requests cannot be tampered with or spoofed. The organization secret can be viewed by organization owners by navigating to Settings > Embedding. It can also be reset from this page if it is ever leaked.

Sensitive Data

The payload, though obscured via the JWT base64 encoding, is not cryptographically secure. While payload data cannot be tampered with without access to the organization secret, sensitive data (e.g. SSNs) should not be included in the payload.

JWT Expiration

By default, we expire JWTs at 24 hours from the iat (issued at) value. Your third party JWT library may generate the iat value for you or require you to include it in your payload. You can lower the expiration time using the exp JWT value however we will always cap the upper bound at 24 hours. The reason for this is we are trying to limit the downside of an end user looking at your HTML source in the browser and distributing the iframe src url outside of your application. At most they could only get away with this for 24 hours.

Revoking End User Access

To revoke end user access to embedded dashboards at any time, reset your organization secret. To do this, visit the embedding settings page and click the Reset Secret button. Please note, this will immediately invalidate embedding requests encoded with the old secret for all dashboards across your entire organization.


URL Length

The URL length of the payload cannot exceed that which browsers support, which is 2,038 characters for Internet Explorer browsers. This means there is roughly 1,700 characters available for hidden variable definitions. This is more than enough for most applications.

Chartio's Native UI Elements

Chartio's native UI elements (date sliders, categorical drop downs, etc.) are disabled for embedded dashboards. This functionality is instead replaced with the more flexible env variables in the JWT payload which allows robust filter and drill capabilities based on UI elements native to the embedding application.