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.
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/embedded0.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.
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.
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.
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}/integrationsand 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 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_INITit trusts. Compare your origin, scheme and port included, withBYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS. -
onConnectDialogCloseis 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
credentialStatusisINVALID. 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_ORIGINSto 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_INITwithout 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,surfaceColorandfontFamily. - 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.







