Qubit Docs العربية

Embed guide

Embedding shows a Qubit dashboard inside your own application. Your users see the dashboard in your app and do not sign in to Qubit. Each user sees only the rows that match the filter values your backend sends for them.

You manage embedding in the Embed & API Keys tab, under Customization in the workspace settings. Only owners and admins can create API keys and set up embeds.

How it works

Embedding has four steps. The Guide button in the Embedded Dashboards section opens the Integration Guide, which covers each step with Python and Node.js examples.

1. Set up the dashboard for embedding

  1. Open the dashboard and choose Embed from its menu.
  2. In the Lock Filters step, choose the columns that separate one customer's data from another's, such as tenant_id. Qubit enforces these locked filters on the server, and the browser cannot change them.
  3. In the Embed Code step, copy the embed ID.

2. Create an API key

  1. In Embed & API Keys, under API Keys, enter a Name and, if you like, a Description.
  2. Click Create Key.
  3. Copy the secret straight away. Qubit shows it only once. If you lose it, revoke the key and create a new one.

You can also create a key in the API Key step of the dashboard's embed dialog.

A workspace can have at most 2 active keys. To create another, click Revoke key on one of them. The key list shows each key's Name, Prefix, Status, Created date, and Last Used date.

3. Create tokens on your backend

When a user opens a page with the embedded dashboard, your backend creates a short-lived token for that user. The token is a JWT signed with HS256 using the key secret. It includes:

  • kid in the header: the API key ID.
  • embed_id: the embed ID from step 1.
  • tenant: a value for every locked filter, for example the user's company ID. If one is missing, Qubit rejects the request.
  • jti: a unique ID. Each token can be used once.
  • exp: the expiry time, no more than 15 minutes ahead.

4. Show the dashboard in your frontend

  1. Load the embed.js script from your Qubit API address. The Integration Guide shows the exact address.
  2. Add a <qubit-dashboard> element where the dashboard should appear.
  3. Fetch a token from your backend and set it as the element's token attribute. The dashboard loads once it has a valid token.

Tokens expire after 15 minutes. If people stay on the page longer, fetch a new token before it expires and set it on the element again. The page does not need to reload.

You can match your app's look with attributes on the element, such as theme, accent-color, and font-family. The Theming section of the Integration Guide lists them all.

Embedded dashboards list

Embedded Dashboards lists the dashboards in this workspace that have an embed setup, with their Locked Filters, Status, Created date, and Tenant Activity.