Copy page

Embed SDK

Embed SDK

Embed Monad's connector-configuration UI directly inside your own product with the public @monad-inc/embed package. Your users connect their own third-party data sources and destinations — an AWS account, an Okta org, a Splunk endpoint — from screens you control, and you never build or maintain the connector forms, secrets handling, or OAuth flows behind them.

The form runs inside a Monad-hosted iframe. Secrets a user types (API keys, OAuth tokens) stay on Monad's origin and never reach your application's JavaScript. Your code gets back a connector id — a safe reference, like Stripe's pm_…. If you've used Stripe Elements or Plaid Link, this is the same isolation model.

When to embed

Reach for embedding when your customers need to bring their own integrations and you'd rather not build the long tail of connector forms, secrets handling, and OAuth. If you only move data between systems you already control, you may not need the embedded UI at all — you can call the Monad API directly (see the Go SDK and Python SDK).

The two pieces you write

Getting running takes two pieces of your own code:

1. A session-mint endpoint on your backend that trades your long-lived Monad API key for a short-lived, team-scoped session token.
2. A createConnectorFrame() call on your frontend that mounts the iframe with that token.

Theming, the connector catalog, and starting data flowing after a connector is saved all build on those two. This overview gets you a working iframe; Authentication & Tenancy, Connector Lifecycle, and the API Reference go deeper.

Architecture

Four parts, one boundary between your systems and Monad's.

Code
     YOUR FRONTEND                       MONAD
+-----------------------+        +------------------------+
|  Your app UI          |        |   Monad iframe         |
|                       | postMsg|   (connector form;     |
|  createConnectorFrame ========>|    secrets live here)  |
|        ^  session tok  |        |                        |
+--------+--------------+        +-----------+------------+
         |                                   |
         | /api/session (your route)         | writes connector
         v                                   v
+-----------------------+        +------------------------+
|  YOUR BACKEND         |  ApiKey|   Monad API            |
|  mints tokens,        |=======>|   POST /v3/sessions    |
|  reads catalog,       |        |   GET  /v1/...         |
|  builds pipelines     |        |   POST /v2/{org}/...   |
|  (API key lives here) |        |                        |
+-----------------------+        +------------------------+

The boundary holds two guarantees:

• Your long-lived API key never leaves your backend. The browser holds only a short-lived session token minted from it. Losing a session token is bounded (one team, a few minutes); losing the API key is not, which is why it stays on the server.
• The secrets a user types never leave Monad's iframe. The iframe runs on Monad's origin, so the browser's same-origin policy stops your JavaScript from reading them.

The session token reaches the iframe over postMessage, not the URL, so it stays out of browser history and the Referer header. The SDK checks the origin on every message in both directions.

Install

The SDK is a public npm package with TypeScript types and no runtime dependencies.

Code
npm install @monad-inc/embed

pnpm add and yarn add work the same. Import the host-side API from the /connect subpath:

Code
import { createConnectorFrame } from '@monad-inc/embed/connect';

Quickstart

Step 1 — mint a session token from your backend

Your backend exchanges its long-lived Monad API key for a short-lived, team-scoped session token, then hands that token to your frontend. It's a plain POST /v3/sessions. Shown here as an Express handler — any HTTP framework works the same way:

Code
// An endpoint on YOUR backend, e.g. POST /api/session
app.post('/api/session', async (req, res) => {
  const { tenantId } = req.body;
  const org = resolveTenantToTeam(tenantId); // your server-side tenant → team mapping

  const r = await fetch('https://app.monad.com/api/v3/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `ApiKey ${process.env.MONAD_API_KEY}`, // key stays server-side
    },
    body: JSON.stringify({ organization_id: org, ttl_seconds: 1800 }), // 30 min
  });

  const session = await r.json(); // { session_token, expires_at }
  res.json({ ...session, organizationId: org }); // merge org id for the frontend
});

The response:

Code
{ "session_token": "eyJhbGc…", "expires_at": "2026-05-26T18:30:00Z" }

Step 2 — mount the iframe on your frontend

Code
import { createConnectorFrame } from '@monad-inc/embed/connect';

// Fetch a fresh session from your own backend.
const s = await fetch('/api/session', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ tenantId: currentUser.tenantId }),
}).then((r) => r.json());

const frame = createConnectorFrame({
  container: '#monad-mount',
  sessionToken: s.session_token, // remap snake_case → camelCase
  organizationId: s.organizationId,
  kind: 'input', // 'input' (a data source) or 'output' (a destination)
  typeId: 'aws-cloudtrail', // connector type slug
  onSave: ({ id }) => {
    // You now have a connector id — build a pipeline next (see Connector Lifecycle).
    frame.destroy();
  },
  onCancel: () => frame.destroy(),
});

That's it. The form renders inside the iframe; the user fills it in and clicks Save; you get a connector id back. The iframe owns its own Save / Test connection / Cancel buttons — your page controls only the surrounding chrome.

:::info Watch the casing The mint response is snake_case (session_token), but createConnectorFrame expects camelCase (sessionToken). Remap at the call site, as shown above. :::

Creating a connector is not moving data

Saving a connector creates it. Data does not move until you build a pipeline that wires the connector to another node. createConnectorFrame gives you the connector id; Connector Lifecycle covers turning that into flowing data, including the zero-setup default sink for a freshly connected source.

Where to go next

• Authentication & Tenancy — the one-team-per-account model, session tokens, and how a tenant maps to a Monad team.
• Connector Lifecycle — build pipelines, ingress vs. egress, pause/resume, and delete/cleanup.
• Best Practices — default inputs and outputs, catalog caching, and deployment.
• API Reference — the full createConnectorFrame options, theming, catalog reads, connector icons, and the backend route contract.

Support

For additional support contact support@monad.com