Originally published on the ByteChef blog. Part 12 of the ByteChef Embedded series.

TL;DR: <AutomationHub jwtToken={token} /> from @bytechef/embedded 0.4.0 puts a complete automations page inside your product. Your users browse the templates you release, connect their own accounts, switch automations on and off, see why one stopped, and manage their connections. On your side: publish a project, release it with an enabled configuration per environment, drop in the component.

The page every integration product ends up building

Once users can create workflows, they need a page to come back to. That page has to answer the everyday questions:

  • Which account is this using?
  • Is it on?
  • Why did it stop?
  • How do I change it?

Building it yourself means a catalog, an activation flow that cleans up after itself when something fails, an on/off switch that explains why it won't turn on, a settings form, a connections list and a way into the builder. That's weeks of work nobody on your team wants to own.

The Automation Hub is that page, already built. It runs in an iframe served by your ByteChef instance, picks up your colors, and only shows what belongs to the user whose JWT you pass in.

The Automation Hub inside the embedded sample app: template cards with Use, Enable and Disable buttons, Needs attention badges and a My Automations section

Five terms you need

Term What it is Who manages it
Automation project A set of workflow templates you build, e.g. "Lead routing" You, in Embedded → Automations
Version A frozen, read-only snapshot of a project, created when you Publish You
Configuration Releases one version of a project to one environment. Has an on/off switch, per-workflow switches, a hub visibility toggle, an assignment rule and provided values You, per environment
Reference A user's automation that points at your template and stores only their connections and inputs Created when the user activates a template
Copy A user's own editable workflow, cloned from your template Created when the user picks Edit workflow

If you remember one thing: publishing doesn't release anything. Users only see a project once an enabled configuration releases it in their environment.

Step 1: Build and publish a project

Projects and templates are only editable in the Development environment. Switch to it at the bottom of the left sidebar, then open Embedded → Automations.

  1. Click New Project. Name and Description are required. Category, Tags and a Permission Expression like metadata['plan'] == 'pro' are optional.
  2. On the Workflows tab, click Create Workflow (or Import Workflow for .json, .yaml, .yml).
  3. Build the template. Every component that needs an app account gets a connection slot. Anything each user fills in themselves, like the Slack channel to post to, goes in the workflow inputs. The hub asks for those during activation.
  4. Publish. The badge goes from V1 DRAFT to V1 PUBLISHED.

Step 2: Release it with a configuration

A configuration puts a published version in front of users in one environment. Create one from New Configuration in the project's ⋮ menu, the Configurations tab, or the editor header.

The key fields:

Field What it does
Version Defaults to the latest published version. Pick an older one to roll back
Assignment rule Optional expression for which new users get this configuration, e.g. metadata['beta'] == 'true'. Empty means everyone
Show in Automation Hub On by default. Off hides the project from the catalog, though its workflows can still be activated by UUID

The New Configuration dialog on its Basic step, with Version, Assignment rule and the Show in Automation Hub switch

On the Workflows step, each workflow has its own switch. Turn one off and that template disappears from the hub in this environment.

Now the step that catches most people: new configurations are saved switched off. Users see nothing until you flip Enable Configuration.

A Configurations tab with an expanded configuration showing a Newer version available badge, its enable switch and per-workflow switches

Provided values

Some settings shouldn't be up to the user. Maybe every customer should post through your Slack bot. Open a workflow's ⋮ Edit in a saved configuration and you get two tabs:

  • Connections: pick Let each user connect or one of your own embedded connections.
  • Inputs: pick Let each user fill it or set a value. Inputs tied to a component property (like a Slack channel) get a real dropdown, loaded through one of your connections.

The Provided Values dialog on its Connections tab

In the hub, provided values show Provided by your administrator instead of a picker. The server rejects any attempt to override them.

Several configurations, one environment

You can run Everyone on V3 and Beta on V4 side by side. Each user lands on exactly one, decided the first time they activate or copy a workflow: ByteChef picks the enabled configuration whose rule matches, preferring the highest version, then the newest configuration.

The rule is checked once. Changing a user's metadata later doesn't move them. To move users on purpose, use Move Users… on a configuration, Upgrade automation in Connected Users, or Change configuration… for a single user.

Rolling out a new version

Publishing V2 changes nothing for your users. To roll it out, use Change Project Version on the configuration. Before you save, the dialog tells you exactly what will happen:

Version 2 adds required input channel to New lead alert: 14 connected users will pause until they fill it. 

On save, references move to the new version and keep each user's connections and inputs. Anything now missing pauses with a reason. Copies stay where they are.

Other actions that touch running automations:

  • Switching off a configuration or workflow pauses its references with "turned off by your administrator". Switch it back on and they resume.
  • Deleting a configuration deletes its references (the dialog tells you how many). Copies keep working.
  • Removing a workflow from the released version leaves dangling references, disabled until the user removes them.

Outside Development you get Automation Configurations instead of Automations: same row actions, no editor. Typical launch: build and publish in Development, test through a Development configuration, then create Staging and Production configurations for the version you tested.

One more prerequisite: every app your templates use needs an embedded integration with an enabled integration configuration in that environment (see part one). Without it, users can't finish activating.

Step 3: Allow your app's origin

Tell the ByteChef server which origins may embed the hub:

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

or in application.yml:

bytechef: embedded: allowed-parent-origins: https://app.example.com,https://admin.example.com 

Exact origins only: scheme, host and port, no paths or wildcards. ByteChef uses the list three ways:

  1. Sends it as Content-Security-Policy: frame-ancestors, so browsers won't render the hub inside any other site.
  2. Sends its EMBED_READY message only to those origins.
  3. Only accepts EMBED_INIT (your props and token) from them.

Leave it empty and any site can embed your hub. Worse, the hub has to guess your page's origin from document.referrer, which breaks when:

  • your page sends Referrer-Policy: no-referrer, or
  • your app is on HTTPS and ByteChef on plain HTTP.

In both cases the hub sits on its loading dots forever. Set the origins and both problems go away.

Step 4: Drop in the component

'use client'; import {AutomationHub} from '@bytechef/embedded'; export function AutomationsPage({jwtToken}: {jwtToken: string}) { return ( <AutomationHub baseUrl="https://bytechef.example.com" className="h-[800px] w-full" environment="PRODUCTION" jwtToken={jwtToken} tabs={{connections: true, newWorkflow: false}} theme={{borderRadius: '0.5rem', mode: 'light', primaryColor: '#2563eb'}} /> ); } 

It renders a <div className={className}> with a full-size iframe inside. Give the wrapper a height or the iframe collapses.

Props

Prop Default What it does
jwtToken required The connected user's token from part one
baseUrl https://app.bytechef.io Your ByteChef host
environment 'PRODUCTION' Which environment's catalog and connections to show
tabs all true automations, connections, newWorkflow
editWorkflowAllowed true Shows Edit workflow and Customize
includeComponents none Limits which components the builder offers
defaultLayout 'grid' 'grid' or 'list'
layoutSwitcherAllowed true Shows the grid/list toggle
theme none Colors, font, corner radius
connectionDialogAllowed true false stops users creating connections in the hub

No callbacks. Everything is saved through the embedded API with the user's JWT.

Lock down connection creation in the token, not the prop

connectionDialogAllowed as a prop only hides buttons. To have the server enforce it, put it in the JWT:

const payload = { sub: externalUserId, name: userName, connectionDialogAllowed: false, }; 

With the claim set to false, connection-create calls get a 403 and the hub hides its Connect buttons, whatever the prop says. Creation is allowed only when both allow it. The claim must be a boolean, or ByteChef rejects the token.

Token refresh is just a re-render

On load, the hub sends EMBED_READY and the component replies with EMBED_INIT carrying its props. When any prop changes, including jwtToken, the component sends a new EMBED_INIT without reloading the iframe. New token or environment means the hub reloads its data for that identity. So refreshing a token is passing a new value.

Theming

theme accepts mode, primaryColor, fontFamily, borderRadius, surfaceColor, cardColor, activeBorderColor, enableColor, disableColor, onAccentColor, segmentColor, plus cssVariables for any other custom property. It applies to dialogs and the builder too.

One catch: the hub is a separate page, so your @font-face rules don't reach it. Stick to fonts the system already has, like system-ui, Arial or Georgia.

What your users get

The catalog

A toolbar (All / Active / Enabled filter, search, grid/list toggle, optional New Automation button) and one card per template the user is allowed to see. Activated cards show the version badge, an Enable/Disable button, a ⋮ menu with Settings, Customize and Remove, and a Needs attention badge with a one-line reason when something blocks it.

The activation dialog

Clicking Use opens up to three steps:

  1. Connect: one account picker per app that isn't provided by you, with a + to connect a new account inline.
  2. Configure: one typed field per input (date, email, number, URL…).
  3. Activate.

The activation dialog on its Connect step, with an account picker and a + button to connect a new account

Under the hood that's at most four calls:

GET /api/embedded/v1/automation/workflows POST /api/embedded/v1/automation/workflow-templates/{templateUuid}/provision POST /api/embedded/v1/automation/workflows/{templateUuid}/enable DELETE /api/embedded/v1/automation/workflow-templates/{templateUuid}/provision # only on failure 

The provision body:

{ "connections": {"slack": 42, "hubspot": 17}, "inputs": {"channel": "#sales"} } 

Connections you leave out are matched automatically to the first usable connection for that app. If provisioning or enabling fails, the dialog deletes the half-created reference so the user retries from a clean state, then maps the error to a human message (a 409 with missingConnectionComponentName jumps back to Connect and highlights the row).

That cleanup logic is the part people usually get wrong when they build this themselves.

Needs attention, explained

Each card's reason comes from attentionReason:

attentionReason What the card says
MISSING_CONNECTION:<component> Connect <component> to keep this running
INPUT_REQUIRED:<input> Fill in <input> to keep this running
INVALID_WORKFLOW:<count> Fix the <count> errors in this workflow to turn it on
TURNED_OFF_BY_ADMINISTRATOR Turned off by your administrator
UPDATE_PENDING Turn it on again to apply the latest update

When the user fills a missing input in Settings, a reference that was only waiting for it starts running again on its own.

Edit workflow

Edit workflow copies the template and opens the copy in the embedded builder from part eleven, inside the same iframe and theme. A new copy has to be published in the builder before it can be enabled.

The Connections tab

The user's connections with a Reconnect needed badge when credentials stop working. Reconnect replaces credentials but keeps the connection ID, so automations using it keep working. Delete is blocked with a 409 if an enabled automation still uses it.

The Connections tab of the Automation Hub listing the user's connections

References vs copies

Reference (from Use) Copy (from Edit workflow)
User owns Their connections and inputs A whole workflow
Editable in the builder No Yes
Gets your new versions Yes No
Provided values Applied and locked Not applied
You switch the workflow off Paused Keeps running

References are what let you fix a template once and roll the fix out to everyone. Want users on references only? Set editWorkflowAllowed={false}.

Building your own hub instead?

Every call goes to /api/embedded/v1 with Authorization: Bearer <JWT> and X-ENVIRONMENT:

Purpose Request
Catalog GET /automation/projects
One template GET /automation/workflow-templates/{uuid}
User's automations GET /automation/workflows
Activate / remove reference POST / DELETE /automation/workflow-templates/{uuid}/provision
Copy POST /automation/workflow-templates/{uuid}/copy
Blank automation POST /automation/workflows
Enable / disable POST / DELETE /automation/workflows/{uuid}/enable
Inputs PUT /automation/workflows/{uuid}/inputs
Publish a copy POST /automation/workflows/{uuid}/publish
Connection picker GET /components/{componentName}/connections
Connections tab GET /connections, DELETE /connections/{id}, POST /connections/{id}/reauthorize

Every /automation/... call also has a server-to-server version at /{externalUserId}/automation/..., authenticated with your environment's API key. Use it to set up automations from your backend, for example right after signup, before the user ever opens the hub.

Gotchas

  • Publishing shows nothing to anyone. You need an enabled configuration, and new ones are saved off. Development included, which is what the sample app uses by default.
  • New configurations don't move existing users. Move them with Change Project Version, Move Users… or Upgrade automation.
  • newWorkflow: false also hides My Automations, which is where users clean up references to templates you removed.
  • The token wins on connections. connectionDialogAllowed: false in the JWT can't be undone by the prop.
  • Custom fonts don't cross the iframe.
  • Set allowed origins before going live, or the hub depends on the browser's referrer to find your page.

Before you go to production

  • Enabled configurations in Staging and Production pointing at the version you tested
  • Hub visibility, workflow switches and provided values set per configuration
  • An enabled integration configuration for every app your templates use
  • Assignment rules based on metadata you actually set
  • BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS set to exact origins
  • connectionDialogAllowed as a JWT claim, not just a prop
  • Tokens refreshed before expiry and passed in as a new prop
  • environment passed explicitly (it defaults to PRODUCTION)
  • A wrapper with a real height
  • A theme that works in light and dark mode
  • A rollout routine: Change Project Version, read the warnings, then save

What you own, what ByteChef owns

You own the templates, which versions are released where, provided values, assignment rules, enabled apps, allowed origins, the JWT and its claims, the page around the iframe, and the theme.

ByteChef owns the catalog, activation and its cleanup, automatic connection matching, version upgrades, attention reasons, the settings form, the connections list, the builder, credential storage, and the engine that runs every automation.

On your side it's one component and a token. Behind it is the whole lifecycle of an automation: release, assign, activate, upgrade, pause, retire.

Try it

Publish a project in Development, create a configuration and switch it on. Run the embedded sample app, open Automation Hub, click Use on a template, connect an account, and watch the card turn into a running automation.

Next up, part 13: the Integration Marketplace, where users browse and connect your integrations without hunting for a template.

ByteChef is open source (Apache 2.0). If this was useful, a star on GitHub helps a lot. The full reference version of this post, with every dialog message and error case, is on the ByteChef blog.