Developer guide

Product managers: send this page to your developers. They only need an embed id, an API key, your Vizkraft base URL, and the liquid tag names you configured.

This guide walks engineering through a complete integration of @vizkraft/embed. For why the API key stays on the server, read Security first. Base URL in production: https://app.vizkraft.com · Product: vizkraft.com

What you will build

A backend route that calls Vizkraft with your embed API key and tenant liquid values, then returns only a short-lived sessionToken to the browser.
A frontend page that installs @vizkraft/embed and mounts the dashboard with getSessionToken.

Prerequisites from your PM

Item	Example	Notes
Base URL	`https://app.vizkraft.com`	Staging may differ
Embed id	`emb_…`	Public; safe in frontend config
API key	`vk_embed_…`	Server secret only
Liquid tags	`customer_id`, `department_id`, …	Values come from your auth at mint time
Allowed origin	`https://your-app.com`	Must include the host that loads the SDK

Step 1 — Install

npm install @vizkraft/embed

Or with a CDN (HTML):

<script type="module">
  import { VizkraftEmbed } from 'https://cdn.jsdelivr.net/npm/@vizkraft/embed/+esm'
</script>

Step 2 — Backend mint

Create a server route your frontend can call (cookie / session auth on your side). That route calls Vizkraft: POST {baseUrl}/api/embed/session Headers:

Authorization: Bearer <YOUR_EMBED_API_KEY>
Content-Type: application/json

Body:

{
  "embedId": "emb_...",
  "liquid": {
    "customer_id": "C1"
  }
}

Return JSON to the browser with only sessionToken (and optionally expiresAt). Never return the API key.

cURL
Node.js
Python

curl -X POST 'https://app.vizkraft.com/api/embed/session' \
  -H 'Authorization: Bearer <YOUR_EMBED_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "embedId": "emb_...",
  "liquid": { "customer_id": "C1" }
}'

// Express example — keep the API key on the server only
app.post('/api/vizkraft-embed-session', async (req, res) => {
  const customerId = req.user.customerId // from YOUR auth
  const r = await fetch('https://app.vizkraft.com/api/embed/session', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VIZKRAFT_EMBED_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      embedId: process.env.VIZKRAFT_EMBED_ID,
      liquid: { customer_id: customerId },
    }),
  })
  const body = await r.json()
  if (!r.ok) return res.status(r.status).json(body)
  res.json({ sessionToken: body.sessionToken, expiresAt: body.expiresAt })
})

# FastAPI example — keep the API key on the server only
import os, httpx
from fastapi import APIRouter, Depends

router = APIRouter()

@router.post("/api/vizkraft-embed-session")
async def mint_embed_session(user=Depends(current_user)):
    async with httpx.AsyncClient() as client:
        r = await client.post(
            "https://app.vizkraft.com/api/embed/session",
            headers={
                "Authorization": f"Bearer {os.environ['VIZKRAFT_EMBED_API_KEY']}",
                "Content-Type": "application/json",
            },
            json={
                "embedId": os.environ["VIZKRAFT_EMBED_ID"],
                "liquid": {"customer_id": user.customer_id},
            },
        )
    data = r.json()
    if r.status_code >= 400:
        return JSONResponse(data, status_code=r.status_code)
    return {"sessionToken": data["sessionToken"], "expiresAt": data.get("expiresAt")}

Step 3 — Frontend mount

Call your backend from getSessionToken. Pass baseUrl when you are not on the default production host.

JavaScript
React
HTML

import { VizkraftEmbed } from '@vizkraft/embed'

const handle = VizkraftEmbed.mount({
  container: '#analytics',
  embedId: 'emb_...',
  baseUrl: 'https://app.vizkraft.com',
  theme: 'dawn',
  height: '100%',
  getSessionToken: async () => {
    const r = await fetch('/api/vizkraft-embed-session', {
      method: 'POST',
      credentials: 'include',
    })
    if (!r.ok) throw new Error('Failed to mint embed session')
    const { sessionToken } = await r.json()
    return sessionToken
  },
  onReady: () => console.log('embed ready'),
  onError: (e) => console.error(e),
})

// later
handle.unmount()

import { useEffect, useRef } from 'react'
import { VizkraftEmbed } from '@vizkraft/embed'

export function AnalyticsEmbed() {
  const ref = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (!ref.current) return
    const handle = VizkraftEmbed.mount({
      container: ref.current,
      embedId: 'emb_...',
      baseUrl: 'https://app.vizkraft.com',
      theme: 'dawn',
      height: '100%',
      getSessionToken: async () => {
        const r = await fetch('/api/vizkraft-embed-session', {
          method: 'POST',
          credentials: 'include',
        })
        if (!r.ok) throw new Error('Failed to mint embed session')
        const { sessionToken } = await r.json()
        return sessionToken
      },
    })
    return () => handle.unmount()
  }, [])

  return <div ref={ref} className="h-full min-h-[480px]" />
}

<div id="analytics" style="height: 100%; min-height: 480px;"></div>
<script type="module">
  import { VizkraftEmbed } from 'https://cdn.jsdelivr.net/npm/@vizkraft/embed/+esm'

  VizkraftEmbed.mount({
    container: '#analytics',
    embedId: 'emb_...',
    baseUrl: 'https://app.vizkraft.com',
    theme: 'dawn',
    height: '100%',
    getSessionToken: async () => {
      const r = await fetch('/api/vizkraft-embed-session', {
        method: 'POST',
        credentials: 'include',
      })
      if (!r.ok) throw new Error('Failed to mint embed session')
      const { sessionToken } = await r.json()
      return sessionToken
    },
  })
</script>

Height tip

Use height: '100%' when the host container is a flex/grid pane that should scroll inside the iframe. Percentage heights do not auto-grow from content. Pixel heights (or omitting height) allow the SDK to resize from viewer vizkraft:resize messages.

Step 4 — Session refresh

You do not build refresh timers. The SDK calls getSessionToken:

On mount
Before session expiry (~5 minutes)
After auth errors from the viewer

Implement getSessionToken as a fresh mint each time (or a short cache on your backend if you prefer).

Step 5 — Verify

onReady fires and charts load for tenant A.
Sign in as tenant B (or mint with different liquid) and confirm KPIs change—isolation works.
Confirm your app origin is listed under Allowed origins in Vizkraft.
Optional: walk through Partner demo on the same deployment.

API quick reference

`VizkraftEmbed.mount(options)`

Option	Type	Description
`container`	`string \| HTMLElement`	CSS selector or element
`embedId`	`string`	`emb_…`
`getSessionToken`	`() => Promise<string>`	Preferred; called on mount / refresh / auth error
`sessionToken`	`string`	One-shot token (no refresh)—prefer `getSessionToken`
`baseUrl`	`string`	Defaults to `https://app.vizkraft.com`
`theme`	`dawn \| mist \| twilight \| dusk \| carbon`	First-paint chrome; admin settings win after bootstrap
`height`	`number \| string`	px number, CSS string, or `'100%'` fill
`onReady`	`() => void`	Viewer ready
`onError`	`(err) => void`	`{ code, message }`

Handle methods

Method	Description
`unmount()`	Tear down iframe and listeners
`refresh()`	Force token refresh + reload
`setTheme(theme)`	Update chrome theme after mount

postMessage (origins checked)

Type	Direction	Purpose
`vizkraft:ready`	viewer → host	Loaded
`vizkraft:resize`	viewer → host	`{ height }` (ignored when height is `%`)
`vizkraft:error`	viewer → host	auth / rate_limit / missing_liquid / …
`vizkraft:setTheme`	host → viewer	`{ theme }`

Common errors

Symptom	Likely cause	Fix
`missing_liquid` / 422	Mandatory tag omitted at mint	Pass all mandatory liquid keys from your auth
401 / auth error	Bad key, revoked key, or expired session	Check server key; let SDK refresh via `getSessionToken`
Blank iframe / framing error	Origin not allowlisted	Add your host under Allowed origins
Charts cut off / no scroll	Host `overflow: hidden` + pixel-growing iframe	Use `height: '100%'` and a sized host pane
Friendly chart empty state	Query failed for that tile	Check coverage / liquid mapping in Vizkraft admin (raw errors show only in-app)

Security — API key + liquid model
Viewer options — themes and chrome toggles
Admin setup — where PMs create keys
Partner demo — end-to-end sandbox
npm: @vizkraft/embed

Get started

Cookbooks

Connect your data

Improve your agent

Ask and analyze

Dashboards

Embed & share

Workspace

Help

What you will build

Prerequisites from your PM

Step 1 — Install

Step 2 — Backend mint

Step 3 — Frontend mount

Height tip

Step 4 — Session refresh

Step 5 — Verify

API quick reference

`VizkraftEmbed.mount(options)`

Handle methods

postMessage (origins checked)

Common errors

​What you will build

​Prerequisites from your PM

​Step 1 — Install

​Step 2 — Backend mint

​Step 3 — Frontend mount

​Height tip

​Step 4 — Session refresh

​Step 5 — Verify

​API quick reference

​VizkraftEmbed.mount(options)

​Handle methods

​postMessage (origins checked)

​Common errors

​Related

What you will build

Prerequisites from your PM

Step 1 — Install

Step 2 — Backend mint

Step 3 — Frontend mount

Height tip

Step 4 — Session refresh

Step 5 — Verify

API quick reference

`VizkraftEmbed.mount(options)`

Handle methods

postMessage (origins checked)

Common errors

Related