​
Steps to Embed Definite

1

Obtain Your API Key

First, you need to obtain your API token from the menu in the Definite web application. See here for more.

2

Generate an Embedded UI Link

Definite typically operates as a single-page web application where users visit ui.definite.app, sign in, and interact with the UI. However, Definite can also be embedded in other web applications, allowing users to access specific canvases directly within an iframe. This guide explains how to embed Definite in your web application.

Next, call the endpoint to generate an embedded UI link:

Endpoint: https://api.definite.app/v1/get_embedded_url

​
Parameters

  • canvas_id: The UUID of the canvas to share.
    • The UUID of a canvas can be found in the URL, after /canvas/
  • user_identifier: A user identifier for the visiting user.
  • required_filters: A set of required filters for the user identifier. These cube filters are applied to all of the user’s queries across all canvases.
    • You can copy a cube block’s filters with Copy Filter JSON button the block settings dropdown menu.

​
Example Query

import requests

DEF_API_KEY = "your-def-api-key"

embed_options = {
    "user_identifier": "your-user-id",
    "canvas_id": "canvas-uuid",
    "required_filters": [
        {
            "member": "mixpanel_events.browser",
            "values": ["Chrome"],
            "operator": "equals"
        }
    ]
}

res = requests.post(
    url="https://api.definite.app/v1/get_embedded_url",
    json=embed_options,
    headers={
        "Authorization": f"Bearer {DEF_API_KEY}"
    }
)

iframe_url = res.json()["url"]
3

Present the Iframe

Finally, present an iframe in your web application with the generated URL. The URL’s OTP will sign in the user, and the iframe will be redirected to a copy of the shared canvas under the new signed-in user.

​
Important Notes

  • User Identifier: The user_identifier defines a user in your team with limited access. This user cannot view other users’ canvases, edit integrations or cube models, or execute SQL blocks. However, they can create their own canvases and blocks.
  • Multiple Calls: You can call get_embedded_url multiple times with different canvases. The user will have a copy of each canvas.
  • Canvas Updates: If you update the source canvas, all downstream users will receive an updated copy on the next get_embedded_url query or a page refresh.
  • Canvas Settings: As the user receives a full copy of your current canvas, any settings, including alerting, schedules, and destinations, will be copied as well.