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.
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.
- Click New Project. Name and Description are required. Category, Tags and a Permission Expression like
metadata['plan'] == 'pro'are optional. - On the Workflows tab, click Create Workflow (or Import Workflow for
.json,.yaml,.yml). - 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.
-
Publish. The badge goes from
V1 DRAFTtoV1 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 |
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.
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.
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:
- Sends it as
Content-Security-Policy: frame-ancestors, so browsers won't render the hub inside any other site. - Sends its
EMBED_READYmessage only to those origins. - 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:
-
Connect: one account picker per app that isn't provided by you, with a
+to connect a new account inline. - Configure: one typed field per input (date, email, number, URL…).
- Activate.
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.
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: falsealso hides My Automations, which is where users clean up references to templates you removed. -
The token wins on connections.
connectionDialogAllowed: falsein 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_ORIGINSset to exact origins -
connectionDialogAllowedas a JWT claim, not just a prop - Tokens refreshed before expiry and passed in as a new prop
-
environmentpassed explicitly (it defaults toPRODUCTION) - 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.






Top comments (0)