Embed SDK

The Querri Embed SDK lets you embed dashboards, projects, and views into any web application. It creates a secure, sandboxed iframe and handles authentication, theming, and communication automatically.

Zero dependencies. Vanilla JavaScript. ~4KB minified.

Installation

npm install @querri-inc/embed

Or load via script tag:

<script src="https://app.querri.com/sdk/querri-embed.js"></script>

Quick Start

<div id="querri-container" style="width: 100%; height: 600px;"></div>

<script src="https://app.querri.com/sdk/querri-embed.js"></script>
<script>
  var querri = QuerriEmbed.create('#querri-container', {
    serverUrl: 'https://app.querri.com',
    auth: { shareKey: 'YOUR_SHARE_KEY', org: 'YOUR_ORG_ID' },
    startView: '/builder/dashboard/DASHBOARD_UUID',
  });

  querri.on('ready', function () {
    console.log('Querri is loaded!');
  });
</script>

Authentication Modes

The SDK supports three authentication modes. Choose based on your use case:

	Share Key	Server Token	Popup Login
User login required?	No	No	Yes
Server-side code needed?	No	Yes	No
User identity available?	No (anonymous)	Yes (per-user via user_id)	Yes (per-user)
Best for	Public dashboards, marketing pages	SaaS embedding, white-label	Internal tools

Mode 1: Share Key (Public Embeds)

For public dashboards and reports that don’t require login. Generate a share key in Querri (Dashboard → Share → Create Link):

QuerriEmbed.create('#container', {
  serverUrl: 'https://app.querri.com',
  auth: {
    shareKey: 'abc123...',
    org: 'org_abc123',
  },
  startView: '/builder/dashboard/DASHBOARD_UUID',
});

Mode 2: Server Token (Enterprise / White-Label)

For embedding Querri behind your own authentication. Your backend exchanges an API key for a scoped session token:

QuerriEmbed.create('#container', {
  serverUrl: 'https://app.querri.com',
  auth: {
    fetchSessionToken: async function () {
      var resp = await fetch('/api/querri-token');
      var data = await resp.json();
      return data.sessionToken;
    },
  },
  startView: '/home',
});

Your backend calls the Querri session endpoint:

curl -X POST https://app.querri.com/api/embed/sessions/token \
  -H "X-API-Key: sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "user_id": "user_01ABC...",
    "dashboard_ids": ["dash_uuid_1"],
    "origin": "https://app.customer.com",
    "ttl": 3600
  }'

Passing user_id is strongly recommended — it enables per-user data isolation, RLS enforcement, and audit attribution. Sessions without user_id use org-wide read-only access and are deprecated.

Mode 3: Popup Login (User Accounts)

For internal tools where users have Querri accounts. The SDK opens a popup for authentication and caches the token for return visits:

QuerriEmbed.create('#container', {
  serverUrl: 'https://app.querri.com',
  auth: 'login',
  startView: '/home',
});

Configuration

Option	Type	Required	Default	Description
serverUrl	string	Yes	—	Your Querri instance URL
auth	string or object	Yes	—	Authentication mode
startView	string	No	null	Initial path (e.g., /builder/dashboard/UUID)
chrome	object	No	{ sidebar: { show: false } }	UI visibility options
theme	object	No	{}	CSS custom property overrides

Events

querri.on('ready', function () { /* Loaded and authenticated */ });
querri.on('error', function (data) { /* { code, message } */ });
querri.on('session-expired', function () { /* Auto-retries in Mode 2/3 */ });
querri.on('navigation', function (data) { /* { path } */ });

Methods

• instance.on(event, callback) — register an event listener
• instance.off(event, callback) — remove an event listener
• instance.destroy() — remove the embed and clean up all resources

Embed UI Configurator

The Querri app includes an interactive Embed UI configurator at Settings → Embed. Use it to:

• Select authentication mode and enter credentials
• Choose which view to embed
• Toggle UI chrome (sidebar, header)
• Apply custom theme colors
• Preview the embed live
• Copy ready-to-use embed code

Security

• All communication uses postMessage with strict origin verification
• Credentials never cross the iframe boundary directly
• The iframe installs a fetch interceptor to attach auth headers internally
• HTTPS is required in production
• API keys (sk_*) should only be used server-side — never expose them in client code

If your site uses a Content Security Policy, allow framing from your Querri instance:

Content-Security-Policy: frame-src https://app.querri.com;

Multiple Embeds

Each QuerriEmbed.create() call creates an independent instance. You can embed multiple views on a single page, each with its own auth and configuration.