Every SaaS that offers integrations ends up building the same page. A grid of cards. A Connect or Connected label on each. An OAuth popup. Loading, empty and error states. A refresh after the user disconnects something. And then you maintain all of it.

In @bytechef/embedded 0.4.0 that page ships prebuilt as one React component:

<IntegrationMarketplace jwtToken={token} /> 

Each of your users sees the integrations they're allowed to use and connects them right there. The catalog runs in an iframe. The Connect dialog runs in your page, so your own callbacks keep working.

The Integration Marketplace in the embedded sample app: a grid of Slack and Gmail cards with Connected labels

This is part 13 of the ByteChef Embedded series. Below: the setup, the code, how the iframe talks to your page, the API underneath, and the gotchas we hit.

TL;DR

  • Upgrade to @bytechef/embedded 0.4.0 or later.
  • Render <IntegrationMarketplace /> with a connected user's JWT.
  • In ByteChef: publish an integration, create a configuration for it, and flip the configuration's Enabled switch. In every environment you use.
  • Add your app's origin to BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS.

Where it fits

ByteChef Embedded now has three ways to put integrations and automations in front of a user:

Hand-built grid (part 1) Integration Marketplace Automation Hub (part 12)
Lists Integrations you shipped Integrations you shipped Automation templates
User ends up with An integration instance An integration instance A running automation
Rendering Your React code Iframe from your ByteChef host Iframe from your ByteChef host
Code you write Fetch, grid, states, refresh One component and a JWT One component and a JWT

On the server the marketplace and a hand-built grid produce the same thing: an integration instance tying the user's connection to one of your integration's configurations. Only who draws the page changes.

Four things before a card shows up

An empty marketplace is almost always a setup issue.

1. Publish an integration

Switch to the Development environment, open Embedded → Integrations and click New Integration. Pick a Component (Gmail, Salesforce, Slack; it can't be changed later) and a Name. Category, Description, Tags and Permission Expression are optional.

The Create Integration dialog with Component, Name, Category, Description, Permission Expression and Tags fields

Add at least one workflow, then publish. Publishing freezes the workflows as a numbered, read-only version. Users only ever run published versions.

2. Enable a configuration

Publishing alone doesn't list anything. A configuration does: it deploys one published version into one environment, with your OAuth app credentials, the workflows you switch on and their default inputs.

  • Development: expand the integration, open its Configurations tab, click Configure.
  • Staging / Production: Embedded → Integration Configurations → New Configuration.

Then the step everyone misses: flip the Enabled switch. New configurations start disabled. Each environment has its own list, so the Production marketplace only shows integrations with an enabled Production configuration.

The Gmail integration on its Configurations tab, with one configuration enabled and its six workflows listed

3. Decide who sees it

Two expressions control visibility. Both are evaluated against the connected user: metadata, externalId, email, name, environment.

  • The integration's Permission Expression gates the integration. Blank means everyone. Anything that doesn't evaluate to true, including a typo, hides it.
  • The configuration's Assignment rule picks which configuration a self-serve user lands on. If several pass, the highest version wins.
metadata['plan'] == 'pro' || metadata['plan'] == 'enterprise' 

Your backend sets metadata, for example with PATCH /api/embedded/v1/me. Values are strings, so compare against quoted literals.

4. Allow your app's origin

BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS=https://app.example.com,https://admin.example.com 

ByteChef sends this as Content-Security-Policy: frame-ancestors ..., and the iframe only accepts its init message from these origins. Scheme, host and port must match exactly. Leave it empty and any site can embed the page (the console warns you).

The code

The sample app's front-end/src/app/integration-marketplace/page.tsx, with field mapping trimmed:

'use client'; import {IntegrationMarketplace} from '@bytechef/embedded'; import {getToken} from '@/lib/api'; import {BYTECHEF_APP_BASE_URL, BYTECHEF_ENVIRONMENT} from '@/lib/config'; import {useEffect, useState} from 'react'; export default function IntegrationMarketplacePage() { const [jwtToken, setJwtToken] = useState<string | null>(null); useEffect(() => { getToken().then(setJwtToken); }, []); if (!jwtToken) { return <div className="w-full p-4">Loading...</div>; } return ( <div className="absolute inset-0 flex flex-col bg-muted lg:pl-72"> <header className="px-4 pt-4"> <h1 className="text-xl font-semibold">Integration Marketplace</h1> </header> <IntegrationMarketplace baseUrl={BYTECHEF_APP_BASE_URL} className="min-h-0 flex-1" environment={BYTECHEF_ENVIRONMENT} jwtToken={jwtToken} mapObjectFields={mapObjectFields} /> </div> ); } 

getToken() asks your backend to sign a connected-user JWT. Never sign it in the browser.

Prop Default What it does
jwtToken required The connected user's JWT
baseUrl https://app.bytechef.io Your ByteChef host
environment 'PRODUCTION' Whose configurations count. Sent as X-Environment
className none Class for the wrapper. The iframe fills it, so give it a height
theme none Colors, font, radius, light or dark
mapObjectFields none Field-mapping callbacks for the Connect dialog
onConnectDialogClose none Called when the Connect dialog closes

How the iframe and your page talk

The component renders ${baseUrl}/integration-marketplace.html and speaks postMessage:

Message Direction When
EMBED_READY iframe → page Loaded, wants parameters
EMBED_INIT page → iframe Sends JWT, environment, theme. Re-sent when they change
EMBED_OPEN_CONNECT_DIALOG iframe → page User clicked Connect or Connected
EMBED_INTEGRATIONS_CHANGED page → iframe Dialog closed, refetch the catalog

The iframe has no credentials of its own. It shows loading dots until EMBED_INIT arrives, then keeps the token in memory. Pass a new token, or a different user signs in on the same tab, and it drops its cache and refetches without reloading the frame.

Both sides check message origins. Your page only opens a dialog for messages from your ByteChef origin and its own iframe window. The iframe only accepts init from an allowed parent origin.

Why the Connect dialog opens in your page

Field mapping is why. mapObjectFields is made of functions: callbacks that list the remote system's object types and fields live, against the user's own connection.

mapObjectFields={{ Contacts: { objectTypes: { get: async ({executeAction, search}) => { const objects = (await executeAction('salesforce', 1, 'listObjects', {search})) as Array<{ id: string; name: string; }>; return objects.map((object) => ({label: object.name, value: object.id})); }, }, // integrationFields, applicationFields ... }, }} 

postMessage can't clone functions. So the iframe doesn't open the dialog. It asks your page to, and your page mounts useConnectDialog with your callbacks right where you defined them, next to your API client and your session. When the dialog closes, the component tells the iframe to refetch, so a card the user just disconnected doesn't keep saying Connected.

Connected opens the same dialog in manage mode: switch workflows on and off, edit inputs, or disconnect. Every change saves immediately. Input edits are debounced 600 ms.

The Connect dialog in manage mode for Gmail, with workflow switches, an INPUTS section and a Disconnect button

No private API

The iframe and the dialog call the same endpoints you'd call yourself, under /api/embedded/v1, with the user's JWT and X-Environment:

Endpoint Called by Does
GET /integrations iframe The user's catalog
GET /integrations/{id} dialog One integration, its workflows and the user's instances
POST /integrations/{id}/instances dialog Connect
POST/DELETE /integration-instances/{id}/workflows/{uuid}/enable dialog Toggle a workflow
PUT /integration-instances/{id}/workflows/{uuid} dialog Save workflow inputs
DELETE /integration-instances/{id} dialog Disconnect

An empty integrationInstances array in the catalog response means Connect. Anything else means Connected.

A few server behaviors worth knowing:

  • The Assignment rule is checked once, at connect. Existing instances keep their configuration, so enabling a newer configuration later doesn't move anybody.
  • Disconnect doesn't break automations. ByteChef deletes the instance and its workflow settings. If the connection is still used elsewhere, it keeps it as one of the user's own connections.
  • Every endpoint has a backend twin (GET /{externalUserId}/integrations and so on), authenticated with your environment's API secret key. Use those for admin views and server jobs.

Build your own, or don't

Our sample app keeps both versions side by side: part one's hand-built grid and the marketplace, on the same data.

The hand-built Integrations page in the sample app, with Other category badges and Connected labels

The hand-built one shows the cost of owning the contract. It read a title field the API doesn't return, so its cards had no headings until we fixed it. Its badge still reads category, which the list response doesn't include, so every card says "Other". With the marketplace, we maintain both sides.

Build your own when the list has to sit inside an existing settings page, mix in your own data, or look like nothing a theme can reach. Otherwise, don't own the page.

Theming

import {type AutomationHubTheme, IntegrationMarketplace} from '@bytechef/embedded'; const theme = { cardColor: '#ffffff', enableColor: '#15803d', fontFamily: 'Inter, sans-serif', mode: 'light', primaryColor: '#2563eb', surfaceColor: '#f4f4f5', } satisfies AutomationHubTheme; <IntegrationMarketplace jwtToken={jwtToken} theme={theme} />; 

Use satisfies, not a type annotation. The prop is typed Record<string, unknown> and TypeScript won't assign an interface-typed value to it. satisfies checks every key and keeps the object's own type. Invalid colors are ignored, not fatal. Only mode reaches the Connect dialog.

Gotchas

  • Published isn't listed. You need an enabled configuration in the marketplace's environment. Check the switch before you debug the component.
  • Environment defaults to PRODUCTION. The sample defaults to DEVELOPMENT. Set it explicitly.
  • The card title isn't your Name field. It's the component's display title. Your description does show.
  • Stuck spinner = handshake problem. The iframe never got an EMBED_INIT it trusts. Compare your origin, scheme and port included, with BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS.
  • onConnectDialogClose is a hint. It fires on connect, disconnect or dismiss, and in 0.4.0 it can fire twice. Make your handler idempotent.
  • Connected doesn't mean healthy. A card says Connected even when credentialStatus is INVALID. Check it from your backend and warn users before a workflow fails.
  • One instance per card. Connected opens the user's first instance. If you allow several per user, manage them from your own page.

Before production

  • Set BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS to every embedding origin, and nothing else.
  • Enable a Production configuration per integration, with production OAuth credentials.
  • Pass environment="PRODUCTION" explicitly.
  • Refresh the JWT before it expires. The component re-sends EMBED_INIT without a reload.
  • Sign in as a user on each plan and check each catalog. An expression error hides the integration.
  • Set at least mode, primaryColor, surfaceColor and fontFamily.
  • Test the round trip per integration: connect, toggle a workflow, edit an input, disconnect.

Try it

Enable a configuration for one of your integrations, upgrade to @bytechef/embedded 0.4.0, run the embedded sample app, and open Integration Marketplace next to Integrations. Connect something in one and watch it turn Connected in the other.

Next in the series: Field Mapping, the full story behind those mapObjectFields callbacks.

ByteChef is an open-source workflow automation and AI agent platform: github.com/bytechefhq/bytechef. The full version of this post, with every request and response, is on our blog.