Embed SDK

@siphon/embed is a small, headless client for surfacing a connection's health inside your own product's UI — so your customer sees "connected / syncing / error" without you building an integrations dashboard.

How it works

Your backend mints a short-lived, connection-scoped embed token (via the control plane). Your frontend hands that token to the embed client, which calls the embed endpoint on the customer's behalf.

Branding

Set your logo, accent colour, and display name once under Settings → Embed → Branding. The embed endpoint returns them with every connection's health, and the widget applies them automatically — your customers see your brand, not Siphon's. No per-embed theming needed (the theme prop still overrides if you want it to).

import { createEmbedClient } from "@siphon/embed";

const client = createEmbedClient({
  baseUrl: "https://app.yourhost.com",
  token, // short-lived, connection-scoped embed token
});

const health = await client.getConnection();
// { connection: { id, displayName, status }, recentRuns: [...] }

getConnection() returns the connection's status and its recent runs — enough to render a status pill, a "last synced" line, or a small run history. It's headless by design: you own the markup.

Token scope

The embed token is scoped to a single connection and short-lived, so it's safe to expose to the browser. It authenticates via an x-siphon-embed-token header — no API key ever reaches the client.

The admin app also ships a reference Connection Widget and an embed preview so you can see the shape before wiring your own UI.

Drop-in React component

@siphon/embed-react wraps the SDK in a themeable, drop-in component — a health pill (incl. overdue), "last synced", and optional recent runs — so you don't build even the widget:

import { ConnectionStatus } from "@siphon/embed-react";

<ConnectionStatus baseUrl="https://app.yourhost.com" token={embedToken} showRuns />

Prefer your own markup? The headless useConnectionHealth({ token, baseUrl, pollMs }) hook returns { data, error, loading, refresh } — the same freshness shape — so you can render whatever you like. Both are self-contained (no CSS import); theme the component via className/style or the colors prop.