Skip to main content

Embedding the Graph Explorer

This guide explains how to safely embed Timbr's Graph Explorer UI as an iframe into an external web page or a BI tool. It covers the required platform settings, how to build the iframe URL (including authentication via a token), Content Security Policy (CSP) considerations, recommended web server snippets, and troubleshooting tips.

Prerequisites​

  • You must have administrative access to the Timbr platform environment to change environment variables.
  • Know the host/domain name where your Timbr instance is reachable (for example, timbr.example.com).
  • A valid Timbr user token (see "Token and authentication" below) with the appropriate permissions to query a knowledge and use the Graph Explorer

Important platform settings​

To allow the Graph Explorer to be embedded, Timbr requires a small number of configuration changes. The following environment variables are supported by Timbr to control iframe embedding behaviour.

  • TIMBR_ALLOW_EMBEDDED_IFRAME

    • Type: boolean-like (any non-empty value enables embedding)
    • Description: When set, Timbr will allow its pages to be framed by other sites (subject to the allowed sources below). If not set, Timbr will send headers that prevent embedding.

  • TIMBR_ALLOW_EMBEDDED_IFRAME_SOURCES

    • Type: comma-separated list of origins (scheme + host + optional port)
    • Description: Values that will be set into the Content-Security-Policy header's frame-ancestors directive (trusted embedding origins). Example: https://reports.example.com,https://app.powerbi.com

Notes:

  • Use exact origins in TIMBR_ALLOW_EMBEDDED_IFRAME_SOURCES (for example include https:// and any required port). Wildcards such as * are not recommended for security reasons.
  • After changing environment variables you will need to restart Timbr (or reload your container/service) for the settings to take effect.

How embedding works (login with token)​

Instead of embedding a page that requires interactive sign-in, Timbr provides a login-by-token endpoint suitable for iframes. The typical pattern is to embed an iframe pointing to /login_with_token/ and provide the user's token and the target path (for example, the saved exploration URL) as query parameters.

Login with Timbr token

Minimal iframe example

<iframe src="https://<your-timbr-host>/login_with_token/" style="width:100%; height:600px; border:0"></iframe>

Troubleshooting​

  • Browser blocks iframe (CSP violation): Check the browser console for a message mentioning frame-ancestors. Confirm the origin of the embedding page is in TIMBR_ALLOW_EMBEDDED_IFRAME_SOURCES and that the origin matches exactly (including scheme and port).
  • Content not loading or authentication denied: Ensure the token is valid, not expired, and has correct permissions. Test the token by calling the Timbr Platform directly.