guides

ByteChef Embedded, Part 13: The Integration Marketplace

ByteChef Embedded, Part 13: The Integration Marketplace
20 min read
Ivica Čardić

TL;DR: The Integration Marketplace is the integrations page from part one, prebuilt: <IntegrationMarketplace jwtToken={token} /> from @bytechef/embedded 0.4.0. Each connected user sees the integrations they're allowed to use and connects them with the same Connect dialog, which still opens in your page so your field-mapping callbacks keep working. On your side, you publish an integration and switch on an enabled configuration for it in each environment.

In part twelve you gave your users a complete automations page in one component: a template catalog, an activation wizard and a Connections tab. That covers the automations your users run. It doesn't cover the other half of an embedded product, the integrations you ship: the Salesforce sync or the Gmail digest you built once and offer to every customer.

For that half you already have a page. In part one your frontend fetched GET /api/embedded/v1/integrations with the connected user's JWT, rendered a card per integration labeled "Connect" or "Connected" depending on whether integrationInstances was empty, opened useConnectDialog from the card, and watched the #connect-dialog-portal node empty out to know when to refresh. It works, but now you own it: loading, empty and error states, icons, refresh, styling and every bug in between.

Nearly every vendor who embeds ByteChef builds that same page, so we ship it. The Integration Marketplace is that catalog as one component, and it keeps what made part one's approach powerful: the Connect dialog still runs in your page, with your callbacks. Here's how to set it up, what the component accepts, what your users get, and which API calls it makes.

The Integration Marketplace in the embedded sample app: a grid of Slack and Gmail cards, each with an icon, description, component name badge and a green Connected label

Where the Marketplace Fits

You now have three ways to put integrations and automations in front of a connected user. They overlap less than it looks:

Hand-built grid (part one)Integration Marketplace (this part)Automation Hub (part twelve)
ListsIntegrations you shippedIntegrations you shippedAutomation templates you published
A user ends up withAn integration instanceAn integration instanceA running automation in their own project
RenderingYour React codeAn iframe from your ByteChef hostAn iframe from your ByteChef host
Connect flowuseConnectDialog, called by youuseConnectDialog, called by the component in your pageInside the hub
Code you writeA data fetch, a grid, states, refresh logicOne component and a JWTOne component and a JWT

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

Before It Lists Anything

An empty marketplace is almost always a setup issue. Four things must be true before a card appears.

1. Build and Publish an Integration

Integrations are authored in the Development environment. Pick it in the environment selector in the left sidebar, open Embedded → Integrations and click New Integration. The Create Integration dialog asks for a Component (the app this integration wraps, such as Gmail, Salesforce or Slack, which can't be changed later) and a Name, prefilled with the component's title. Category, Description and Tags are optional, and so is the Permission Expression, which we'll get to in step 3.

Add at least one workflow, then publish from the row's ⋮ menu (Publish stays disabled until there's a workflow) or with the Publish button in the workflow editor's header. Publishing freezes the current workflows as a numbered, read-only version, and connected users only ever run published versions.

The Create Integration dialog under Embedded → Integrations, with Component, Name, Category, Description, Permission Expression and Tags fields

2. Turn On a Configuration

Publishing alone doesn't list an integration; 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.

In Development there's no Integration Configurations sidebar entry. Expand the integration on Embedded → Integrations, open its Configurations tab and click Configure (or New Configuration once one exists). The ⋮ menu's New Configuration item and the editor's Configure button open the same wizard, and until the integration is published all of them are disabled with "Publish the integration before configuring it." In Staging and Production, the Integrations entry gives way to Embedded → Integration Configurations: click New Configuration and pick the integration in the Integration combobox.

The wizard has up to three steps. Basic takes the Integration, a Name, the published Version to deploy, an optional Assignment rule and, outside Development, Tags. OAuth2 Connection appears only for components that authenticate with OAuth2 and holds your OAuth app's client credentials. Workflows lets you switch each workflow on and set its inputs. Click Save.

Then comes the step people miss: flip the Enabled switch on the configuration's row. New configurations start disabled, and only enabled ones count. Each environment has its own list, so the DEVELOPMENT marketplace shows integrations with an enabled configuration in Development, and the PRODUCTION marketplace those with one in Production.

The Gmail integration expanded on its Configurations tab: one configuration with its Enabled switch on and its six workflows listed below

3. Decide Who Sees It

Two expressions decide whether a given user sees a given integration. Both are evaluated against the same context, built from the connected user: metadata, externalId, email, name and environment.

The integration's Permission Expression gates the integration itself. Blank means everyone; anything that doesn't evaluate to true, including a typo or an evaluation error, hides it. The configuration's Assignment rule decides which configuration a self-serve user lands on. The marketplace lists an integration only when at least one of its enabled configurations lets the user in, and on connect ByteChef picks the highest version among those (the newest one on a tie). A typical rule:

metadata['plan'] == 'pro' || metadata['plan'] == 'enterprise'

metadata is whatever your backend attaches to the connected user, for example with PATCH /api/embedded/v1/me and the user's JWT. Values are stored as strings, so compare against quoted literals.

One exception: if a user already has an instance on an enabled configuration (say an admin provisioned it), the integration stays in their catalog even when no assignment rule would let them self-serve it. The integration's permission expression still applies. Expressions can also hide individual workflows inside an integration; that gets its own part later in the series.

4. Allow Your App's Origin

The marketplace is one of three pages ByteChef lets other sites frame, with the Automation Hub and the workflow builder. In production, tell the server which origins your app runs on:

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

That's the bytechef.embedded.allowed-parent-origins property. ByteChef sends the list as Content-Security-Policy: frame-ancestors ... on integration-marketplace.html, so no other site can frame it, and the page only accepts its init message from those origins. Trailing slashes are stripped; scheme, host and port must match exactly. With the list empty, any site can embed the page, and the browser console says so.

Dropping It In

The code is short. Here's the sample app's marketplace page, front-end/src/app/integration-marketplace/page.tsx, with the field-mapping callbacks trimmed (they get their own section below):

'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() is part one's helper: it asks the sample's backend to sign a connected-user JWT and caches it until shortly before expiry. The page waits for the token because jwtToken is the one prop the component can't do without.

The props, all from sdks/frontend/embedded/library/src/components/integration-marketplace:

PropTypeDefaultWhat it does
jwtTokenstring(required)The connected user's JWT from part one.
baseUrlstringhttps://app.bytechef.ioYour ByteChef host. The iframe loads from here and the Connect dialog calls its API.
environment'DEVELOPMENT' | 'STAGING' | 'PRODUCTION''PRODUCTION'Whose configurations count. Sent as X-Environment.
classNamestringnoneClass for the wrapping div. The iframe fills it at 100% width and height, so give it a height.
themeobjectnoneColors, font, radius and light or dark mode. See Theming.
mapObjectFieldsMapObjectFieldsTypenoneField-mapping callbacks handed to the Connect dialog.
onConnectDialogClose() => voidnoneCalled when the user closes the Connect dialog.

On typing: the props interface isn't exported, and theme is loosely typed as Record<string, unknown>. To have the compiler check your theme, use the exported AutomationHubTheme type (the marketplace reads the same keys) with satisfies rather than a type annotation, as in Theming. MapObjectFieldsType is exported too.

The Handshake

The component renders an iframe at ${baseUrl}/integration-marketplace.html#/embedded/marketplace and talks to it with postMessage, using four message types:

MessageDirectionCarriesWhen
EMBED_READYiframe to your pagenothingThe page has loaded and wants its parameters
EMBED_INITyour page to iframeparams: {environment, jwtToken, theme}In answer to EMBED_READY, and again whenever those props change
EMBED_OPEN_CONNECT_DIALOGiframe to your pageintegrationId (a string)The user clicked Connect or Connected
EMBED_INTEGRATIONS_CHANGEDyour page to iframenothingThe Connect dialog closed; refetch the catalog

The iframe has no credentials of its own. Until EMBED_INIT arrives it shows loading dots and doesn't request the catalog; afterwards it keeps the token and environment in memory and sends them as Authorization: Bearer <JWT> and X-Environment. Change jwtToken, environment or theme after the iframe is ready and the component sends a fresh EMBED_INIT without reloading the frame. If the token or environment changed, the page drops its cached data and refetches, so a refreshed token, or a different user signing in on the same tab, never shows the previous user's catalog.

Both sides check where messages come from. Your page accepts EMBED_READY only from your ByteChef host's origin, and EMBED_OPEN_CONNECT_DIALOG only from that origin and its own iframe's window, so no other frame can make it open a dialog. The iframe accepts EMBED_INIT only from its parent window and only from an allowed parent origin. It sends EMBED_OPEN_CONNECT_DIALOG only to the origin that initialized it, and accepts EMBED_INTEGRATIONS_CHANGED only from that same parent.

What Your Users See

Users get a responsive grid of cards, one to four columns wide. Each card has the integration's icon; a title from the API's name field, which carries the component's display title (Gmail, Salesforce) and falls back to the component name; your description, or the component's own if you left it blank, clamped to three lines; a badge with the component name (gmail, salesforce); and a button reading Connected (in your theme's enable color) when the user already has an instance, Connect otherwise.

While loading, the page shows loading dots. A failed request shows an Unable to load integrations alert with the error, and an empty result says There are no integrations available yet., which is what you'll see if you skipped step 2.

Connect opens part one's ConnectDialog, running the OAuth2 or API key flow for that integration. For OAuth2, the provider's consent screen opens in a separate window from your page, exactly as with the hook.

Connected opens the dialog too. Since the marketplace doesn't name an instance, the dialog falls back to the user's first instance of that integration and opens in manage mode: switch workflows on and off, edit their inputs, or disconnect.

The Connect dialog in manage mode for a connected Gmail integration, listing three workflows with on and off switches, an INPUTS section and a Disconnect button
ConnectDialog in manage mode for Gmail, with Workflows and Tools tabs, an Echo Request workflow switched on, no inputs defined, and a red Disconnect button

Manage mode saves each change as it's made, so there's no Save button to forget. A workflow switch sends POST (on) or DELETE (off) to /api/embedded/v1/integration-instances/{id}/workflows/{workflowUuid}/enable. Input edits are debounced for 600 ms, then saved with a PUT to /api/embedded/v1/integration-instances/{id}/workflows/{workflowUuid}.

Why the Dialog Opens in Your Page

The catalog lives in an iframe, but the Connect dialog doesn't. Here's the round trip when a user clicks Connect:

  1. The iframe posts EMBED_OPEN_CONNECT_DIALOG with the integration's id, addressed only to the page that initialized it.
  2. The component checks the message's origin and source window, as described above, and ignores anything else.
  3. The component mounts useConnectDialog in your page for that integration, passing your baseUrl, jwtToken, environment, mapObjectFields and theme.mode, and opens it.
  4. When the dialog closes, the component posts EMBED_INTEGRATIONS_CHANGED back to the iframe, which refetches its catalog, and then calls your onConnectDialogClose.

Step three is why. mapObjectFields is how a Connect dialog renders field mapping, a workflow input that asks the user to pair your application's fields with fields in their connected app. It's made of functions: callbacks that list the remote system's object types and fields live, against the user's own connection. The sample's, from the same page file:

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: {
            get: async ({executeAction, objectType}) => {
                const fields = (await executeAction('salesforce', 1, 'listObjectFields', {objectType})) as Array<{
                    id: string;
                    label: string;
                }>;

                return fields.map((field) => ({label: field.label, value: field.id}));
            },
        },
        applicationFields: {
            fields: [
                {label: 'Title', value: 'title'},
                {label: 'Email', value: 'email'},
            ],
            defaultFields: [],
            userCanCreateFields: true,
            userCanRemoveMappings: true,
        },
    },
}}

postMessage carries strings, numbers, arrays and plain objects into an iframe, but throws on functions, so callbacks could never reach a dialog inside the catalog's iframe. In your page they stay where you defined them, next to your API client, your session and your feature flags.

Step four covers the other direction. Connecting and disconnecting happen in your page, which the iframe can't observe, so without the refresh message a card the user just disconnected would say Connected until a reload.

What Happens on the Server

There's no private API here. The iframe and the dialog use the same embedded endpoints you'd call yourself, under /api/embedded/v1, authenticated with the connected user's JWT:

EndpointCalled byWhat it does
GET /integrationsThe iframeThe user's catalog
GET /integrations/{id}The dialog, on openOne integration with its workflows, connection form and the user's instances
POST /integrations/{id}/instancesThe dialog, on ConnectCreates the user's instance from {connection: {parameters}} and returns its id
POST, DELETE /integration-instances/{id}/workflows/{workflowUuid}/enableThe dialog, manage modeSwitches one workflow on or off for this user
PUT /integration-instances/{id}/workflows/{workflowUuid}The dialog, manage modeSaves the workflow's inputs
DELETE /integration-instances/{id}The dialog, DisconnectRemoves the instance; answers 204

Every request carries Authorization: Bearer <JWT> and X-Environment. A missing or invalid token gets 401.

Listing the Catalog

GET /api/embedded/v1/integrations
Authorization: Bearer <connected user's JWT>
X-Environment: DEVELOPMENT
[
    {
        "componentName": "gmail",
        "description": "Gmail is the email service developed by Google...",
        "icon": "<svg ...>...</svg>",
        "id": 1052,
        "integrationInstances": [
            {
                "connectionId": 1187,
                "credentialStatus": "VALID",
                "enabled": true,
                "id": 1201,
                "integrationInstanceConfigurationId": 1050,
                "integrationVersion": 2,
                "workflows": [{"enabled": true, "inputs": {}, "workflowUuid": "..."}]
            }
        ],
        "integrationVersion": 2,
        "multipleInstances": false,
        "name": "Gmail"
    }
]

ByteChef resolves the connected user from the token's subject and the environment from the header, then for each integration:

  1. Collects the integration's enabled configurations in that environment.
  2. Keeps the ones whose Assignment rule lets the user in, and picks the one with the highest version (the newest one on a tie). If none pass but the user already has an instance on an enabled configuration, it uses that configuration instead.
  3. Drops the integration if its Permission Expression hides it from this user.
  4. Attaches the user's instances of it, each with its connection's credentialStatus (VALID or INVALID) and the state of its workflows.

An empty integrationInstances array means Connect; anything else means Connected, in the iframe and in part one's hand-built grid alike.

Connecting and Disconnecting

Connect posts the connection form's values to /integrations/{id}/instances. ByteChef reruns the selection to pick this user's self-serve configuration at that moment (the Assignment rule is checked here, once), creates the connection, and creates an instance on that configuration. Existing instances keep the configuration they were created on, so enabling a newer configuration later doesn't move anybody.

Disconnect sends DELETE /integration-instances/{id}. ByteChef refuses if the instance belongs to another connected user. Otherwise it switches off the instance's workflows, deletes the instance and its workflow settings, and then handles the connection: if nothing else uses it, it's deleted; if something still does (one of the user's automations, say), ByteChef keeps it as one of the user's own connections rather than break that automation.

From Your Backend

Each endpoint also has a backend form with the user's ID in the path, authenticated with your environment's API secret key instead of a JWT: GET /{externalUserId}/integrations, POST /{externalUserId}/integrations/{id}/instances and so on. The marketplace never calls them; they're for your own admin views and server jobs.

The Sample App: Two Integrations Pages

The embedded sample app keeps both versions side by side on the same data. The sidebar has Integrations (/integrations, part one's hand-built grid) and Integration Marketplace (/integration-marketplace, this part).

The hand-built Integrations page in the sample app, with Slack and Gmail cards carrying Other category badges and Connected labels, and both Integrations and Integration Marketplace in the sidebar
front-end/src/app/integrations/page.tsxfront-end/src/app/integration-marketplace/page.tsx
CatalogIts own fetch to /api/embedded/v1/integrationsLoaded inside the iframe
Cards, empty and error statesIts own JSX; a loading line, but no empty or error stateBuilt in, themed by theme
Card titleintegration.namename, falling back to componentName
Badgeintegration.category ?? 'Other'The component name
Connect / ConnectedIts own check on integrationInstances.lengthBuilt in
Opening the dialogA ConnectDialogOpener that calls useConnectDialogMounted by the component, in your page
Refresh after closeA MutationObserver on #connect-dialog-portalEMBED_INTEGRATIONS_CHANGED, then onConnectDialogClose
Field mappingmapObjectFields on the hookThe same object on the component

The hand-built page shows the cost of owning that contract. It used to read a title field the API doesn't return, so its cards had no headings until a recent fix switched it to name. Its badge still reads category, which the list response doesn't include, so every card says Other. With the marketplace, ByteChef maintains both sides.

Building your own still makes sense when the list has to sit inside an existing settings page, mix in your own data, or look like nothing ByteChef can theme. Use part one's API there, with the table above as your checklist. The marketplace is for when you'd rather not own the page at all.

Theming

The marketplace reads the same theme object as the Automation Hub. The keys that change the catalog:

KeyAffects
mode'light' or 'dark' for the catalog, and the Connect dialog
surfaceColorThe page background behind the cards
cardColorThe cards
enableColorThe Connected label
primaryColorThe brand color the page's components derive their accents from
fontFamilyThe page font
borderRadiusCorner radius, as a px, rem, em or % length
cssVariablesAny CSS custom property you want to set directly; keys must start with --
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} />;

Why satisfies? AutomationHubTheme is an interface, and TypeScript won't assign an interface-typed value to the prop's Record<string, unknown>. satisfies checks every key and value against the interface while keeping the object's own type, which the prop accepts.

Colors must be hex values or anything CSS.supports('color', ...) accepts; invalid values are ignored rather than breaking the page. Only mode crosses into the Connect dialog: the dialog is part of the SDK and renders in your page, so its colors don't follow the rest of theme.

Gotchas

  • Published isn't listed. An integration needs an enabled configuration in the marketplace's environment, and a new configuration starts disabled. Check the Enabled switch before you debug the component.
  • The environment must match. The environment prop picks whose configurations count, and it defaults to PRODUCTION. The sample defaults to DEVELOPMENT; set it explicitly.
  • The title isn't your Name field. The card's title is the component's display title, so renaming the integration in the Create Integration dialog doesn't change it. The description you write does show.
  • A stuck spinner is a handshake problem. If the iframe never leaves its loading dots, it never received an EMBED_INIT it trusts. Compare your app's origin, scheme and port included, with BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS. A blank frame with a frame-ancestors error in the console is the same mistake, caught one step earlier by the browser.
  • onConnectDialogClose is a hint. It fires whether the user connected, disconnected or just dismissed the dialog, and in 0.4.0 it can fire more than once for a single close. Treat it as "something may have changed" and make your handler idempotent: a refetch rather than a counter.
  • Connected doesn't mean healthy. A card reads Connected whenever an instance exists, even if its connection's credentialStatus is INVALID. There's no reconnect button, so the user has to Disconnect and Connect again. If credentials often expire for an app, check credentialStatus from your backend and warn the user before a workflow fails.
  • One instance per card. Connected always opens the user's first instance of the integration. If you allow several instances of one integration per user, manage them from a page of your own.
  • Check the package version. IntegrationMarketplace needs @bytechef/embedded 0.4.0 or later.

Before You Go to Production

  • Set BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS to every origin that embeds the marketplace, and nothing else.
  • Enable a Production configuration for each integration you want listed, with your production OAuth app credentials in its OAuth2 Connection step.
  • Pass environment="PRODUCTION" explicitly, along with the matching environment on every other embedded call your app makes.
  • Keep the JWT fresh, and sign it on your backend, never in the browser. The sample fetches one token on mount; in a long session, pass a new one before the old one expires and the component re-sends EMBED_INIT without a reload.
  • Test your expressions: set the connected user's metadata from your backend, sign in as users on each plan, and check each catalog. An expression error hides the integration.
  • Set a theme, with at least mode, primaryColor, surfaceColor and fontFamily, so the catalog and the dialog look like your product.
  • Test the whole round trip once per integration: connect, switch a workflow, edit an input, disconnect, and watch the card change each time.

What You Own, What ByteChef Owns

  • You own where the marketplace appears and how big it is, the JWT and its freshness, the environment, the theme, the connected user's metadata, the integrations you publish and the configurations you enable, the visibility expressions, and any field-mapping callbacks.
  • ByteChef owns the catalog page and its loading, empty and error states, the per-user visibility rules, the cross-frame protocol and its origin checks, the Connect dialog and every OAuth2 or API key flow behind it, credential storage and refresh, the integration instances and their workflow settings, and the engine that runs those workflows.

On your side it's one component, a JWT and, if you map fields, the callbacks you'd have written anyway.

What's Next

Those mapObjectFields callbacks got one code block here and deserve more. The next part, Field Mapping, covers how a workflow declares a field-mapping input, how the dialog turns your callbacks into an object-type picker and mapping rows, what executeAction really runs, and how the saved mapping reaches a running workflow.

Thirteen Parts In

Here's the whole series so far:

  1. Connect your users' apps (the JWT and ConnectDialog everything rests on).
  2. Act on those connected apps directly with the ComponentKit.
  3. Chat with an AI assistant that uses the ComponentKit's tools.
  4. Trigger their workflows from your product's events.
  5. Call a workflow like a synchronous API.
  6. Agent over MCP: the same tools, discovered through an open protocol.
  7. Author workflows in a builder you designed yourself.
  8. Start from a template you curated.
  9. Talk a workflow into existence with ByteChef's agent.
  10. Describe it in one sentence and get a finished workflow back.
  11. Edit on ByteChef's own canvas, embedded in your product.
  12. Hand users a complete automations page with the Automation Hub.
  13. Hand users a complete integrations page with the Integration Marketplace (this part).

Parts one through ten gave you building blocks; eleven through thirteen give you whole pages. The workflow builder, the Automation Hub and the Integration Marketplace each run in an iframe on your ByteChef host with the same EMBED_READY / EMBED_INIT handshake, on the same JWT and embedded API as the blocks. Use the pages where they fit, and drop back to the blocks wherever a page has to be entirely yours.

Following along? 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 show up as Connected in the other.

Subscribe to the ByteChef Newsletter

Get the latest guides on complex automation, AI agents, and visual workflow best practices delivered to your inbox.

Related posts