Building a visual workflow editor is the most expensive part of any integration product. Canvas, node palette, property forms, data mapping, test runs, versioning. Teams spend years on it.
Here's the shortcut: create a workflow with one REST call, then render ByteChef's own editor inside your page with one React component. Your users get the full canvas. You write a dialog, a fetch and a page.
This is part 11 of the ByteChef Embedded series. All code comes from the open-source embedded sample app. The full original is on the ByteChef blog.
The 30-second version
<EmbeddedWorkflowBuilder baseUrl="https://bytechef.your-company.com" environment="PRODUCTION" jwtToken={jwtToken} workflowUuid={workflowUuid} /> - It's an iframe that loads
workflow-builder.html#/embedded/builder/{uuid}from your ByteChef host. - The user's JWT goes in over
postMessage, never in the URL. - Inside, the user gets the real editor: triggers, actions, flow controls, data pills, connections, Test and Publish.
- You decide which components show up, whether users can create connections, and where the editor sits in your layout.
Where it fits
The sample app has five ways to create a workflow. All five end in the same place: a workflow in the connected user's own project. They differ in who does the authoring.
| Option | Who authors the steps | Best when |
|---|---|---|
| New from Template | You, ahead of time | You know the common automations up front |
| New from Embedded Workflow Builder | The user, on ByteChef's canvas | Users who think in triggers and steps and need the full catalog |
| New from Prompt | ByteChef's agent, from one sentence | Short, clear requests |
| New from Chat | ByteChef's agent, together with the user | Fuzzy requests |
| New from Custom Workflow Builder | The user, in forms you designed | You want full control of the UX |
The embedded builder is the most powerful option for the user and one of the cheapest for you.
The flow
- The user clicks New from Embedded Workflow Builder and enters a label and description.
- Your app calls
POST /api/embedded/v1/automation/workflows. ByteChef stores a draft in the user's project and returns its UUID. - Your app opens
/automations/{uuid}, which rendersEmbeddedWorkflowBuilder. - The user builds, tests and publishes inside the editor.
- Back in your list, the user flips a toggle to enable it.
Steps 1 to 3 are yours. Step 4 is ByteChef's. Step 5 is yours again.
Step 1: Create the workflow
POST /api/embedded/v1/automation/workflows Authorization: Bearer <connected user's JWT> X-Environment: DEVELOPMENT Content-Type: application/json {"definition": "{\"label\": \"Sync new notes\", \"description\": \"\", \"triggers\": [], \"tasks\": []}"} The response is the new workflow's UUID as a JSON string. Note that definition is the workflow JSON as a string.
What ByteChef does with it:
- Finds or creates the user's project. Every connected user gets one personal project per environment, named after their external user ID.
- Adds the workflow as a draft. No published version yet, so it can't be enabled.
- Fills in a blank definition if you send an empty string. The editor then shows a Manual trigger placeholder on a clean canvas.
The sample app's create call is a demo shortcut. It hardcodes a Productboard trigger, builds JSON by string interpolation (a label with a " in it breaks it), and throws the returned UUID away. Do this instead:
export async function createBlankWorkflow(label: string, description: string): Promise<string> { const response = await fetchWithAuth('/api/embedded/v1/automation/workflows', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ definition: JSON.stringify({description, label, tasks: [], triggers: []}), }), }); if (!response.ok) { throw new Error(`Failed to create workflow: ${response.status}`); } return response.json(); } // in your submit handler const workflowUuid = await createBlankWorkflow(values.label, values.description); router.push(`/automations/${workflowUuid}`); fetchWithAuth is a small wrapper that adds Authorization: Bearer <JWT> and X-Environment. Now the user lands on the canvas the moment they click Create.
Step 2: Embed the editor
The whole integration is one Next.js page:
import {EmbeddedWorkflowBuilder} from '@bytechef/embedded'; import {getToken} from '@/lib/api'; import {BYTECHEF_APP_BASE_URL, BYTECHEF_ENVIRONMENT} from '@/lib/config'; export default async function AutomationPage({params}: {params: {workflowUuid: string}}) { const {workflowUuid} = await params; const jwtToken = await getToken(); return ( <EmbeddedWorkflowBuilder baseUrl={BYTECHEF_APP_BASE_URL} connectionDialogAllowed={true} environment={BYTECHEF_ENVIRONMENT} jwtToken={jwtToken} workflowUuid={workflowUuid} /> ); } It's a server component that fetches the JWT while rendering. The SDK marks the component 'use client', so you don't need a wrapper.
Props (@bytechef/embedded 0.4.0)
| Prop | Type | Default | What it does |
|---|---|---|---|
jwtToken | string | required | The connected user's JWT, sent to the iframe over postMessage |
workflowUuid | string | required | The workflow to open |
baseUrl | string | https://app.bytechef.io | Your ByteChef host. Self-hosted installs must set it |
environment | `'DEVELOPMENT' \ | 'STAGING' \ | 'PRODUCTION'` |
includeComponents | string[] | all components | Limits the palette, e.g. ['slack', 'googleMail'] |
connectionDialogAllowed | boolean | required | Whether users can create connections inside the editor |
That's the full list. No onSave, onPublish or onClose callbacks, and no theme prop. Everything the user does is saved by ByteChef inside the iframe.
Size the container yourself
The component renders a 100% x 100% iframe inside a wrapper with Tailwind classes (absolute inset-0 lg:pl-72). The SDK ships no CSS for those, so they only work if your stylesheet happens to define them. Give it a positioned parent with a real height:
<div style={{height: 'calc(100vh - 64px)', position: 'relative'}}> <EmbeddedWorkflowBuilder {...props} /> </div> How the iframe gets the user's identity
The iframe URL carries only the workflow UUID. The JWT travels through a two-message handshake:
- Iframe to parent:
EMBED_READY. The editor reads the allowed parent origins from your ByteChef server and posts only to those. - Parent to iframe:
EMBED_INIT. The SDK ignoresEMBED_READYunless it comes from the origin ofbaseUrl, then replies with{connectionDialogAllowed, environment, includeComponents, jwtToken}, addressed to that origin only. - The editor initializes. It accepts
EMBED_INITonly from its parent window and an allowed origin, stores the token and loads the workflow.
From then on every request the editor makes carries Authorization: Bearer <JWT> and X-Environment. The editor has no ByteChef login of its own. The token is the session, scoped to one connected user in one environment. Loading, saving, testing and publishing only ever touch that user's project.
Refresh the token without a reload
The SDK re-sends EMBED_INIT whenever its props change. Pass a new jwtToken and the editor swaps it in without reloading the iframe. The sample fetches a single token that lives for an hour, so an editor left open longer starts failing. The fix is a small client wrapper:
'use client'; import {EmbeddedWorkflowBuilder} from '@bytechef/embedded'; import {useEffect, useState} from 'react'; export default function WorkflowEditor({initialToken, workflowUuid}: WorkflowEditorPropsI) { const [jwtToken, setJwtToken] = useState(initialToken); useEffect(() => { const interval = setInterval(async () => setJwtToken(await fetchFreshToken()), 5 * 60 * 1000); return () => clearInterval(interval); }, []); return ( <div style={{height: 'calc(100vh - 64px)', position: 'relative'}}> <EmbeddedWorkflowBuilder baseUrl={BYTECHEF_APP_BASE_URL} environment={BYTECHEF_ENVIRONMENT} jwtToken={jwtToken} workflowUuid={workflowUuid} /> </div> ); } fetchFreshToken calls your own token endpoint. Refresh well before the token's exp.
Lock down who can frame it
BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS=https://app.example.com,https://admin.example.com Exact origins with scheme and port, no paths, no wildcards. ByteChef then sends Content-Security-Policy: frame-ancestors with those origins and accepts EMBED_INIT only from them. Leave it empty and any site can frame your editor.
If the editor is blank, check the console:
-
frame-ancestorsviolation: your app's origin isn't on the list. - Stuck on loading: the editor never got
EMBED_INITfrom an allowed origin. Check http vs https and the port. - Empty list plus
Referrer-Policy: no-referrer: the editor can't announce itself. Set the list.
Match the environment to the token
ByteChef verifies the JWT against the signing key registered for the request's environment. A Development token used with environment="PRODUCTION" is rejected. The prop defaults to PRODUCTION, so set it explicitly.
What the user sees inside
The same canvas ByteChef's own users build with, scoped to one workflow:
- Header: workflow label with a
V1 DRAFTbadge, Saving... / Offline, Test, Publish, the output panel and a settings menu to rename the workflow. - No way out. No project sidebar, no workflow switcher, no navigation to the rest of ByteChef. Your app owns navigation. The AI Copilot and the workflow inputs panel are turned off.
- Autosave. There's no Save button. The
DRAFTbadge tells the user they're editing the draft, not what's running.
Narrow the palette
By default the palette lists every component on your ByteChef instance, not only the integrations you configured. Narrow it:
<EmbeddedWorkflowBuilder // ... includeComponents={['googleMail', 'slack', 'hubspot']} /> Flow controls stay available either way. Treat includeComponents as product design, not as a permission: it comes from your page, and the server doesn't check saved workflows against it.
Control connection creation in the token
On a step that needs an account, the user picks from their own connections and any a tenant admin shared. No other user's connections ever appear. If there are none, a Create Connection button opens ByteChef's connection form inside the iframe.
connectionDialogAllowed={false} hides that button. But a page is easy to change. For a rule the server enforces, put it in the JWT:
const token = jwt.sign( { connectionDialogAllowed: false, sub: externalUserId, }, privateKey, {algorithm: 'RS256', expiresIn: '10m', keyid: signingKeyId} ); - Claim missing or
true: users can create connections. - Claim
false: existing connections only, and the API answers create attempts with403. - Claim not a boolean: the token is invalid.
A false prop hides creation even when the token allows it. A true prop can't override a token that says false. The claim is per token, so mint separate tokens for surfaces with different rules.
Test and publish
Test runs the current draft with the connections chosen on each step. These are real calls: a test that sends a Slack message sends a Slack message from the user's account. Say so in your onboarding.
Publish freezes the current definition as the next version (V1, V2 and so on) and deploys it with the chosen connections. The user keeps editing a new draft, and nothing reaches the running workflow until they publish again.
Enabling happens in your app
The editor has no on/off switch. That's deliberate: where an automation is turned on and what you show next to it are product decisions.
// Turn it on (DELETE to turn it off) const response = await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/enable`, { method: 'POST', }); If the published version has validation errors, you get 409 with a body like {"invalidWorkflowErrorCount": 2}. Show the count and link back to the editor. A workflow that was never published can't be enabled.
Theming
There's no theme prop, and your CSS can't reach inside the iframe. You control placement and the catalog. You don't control colors, fonts or copy in the standalone editor. If you need it in your brand colors, the Automation Hub (part 12) applies a theme to the same editor.
Server-to-server variant
Want to prepare a workflow before the user arrives, like a starter automation during onboarding? Call POST /api/embedded/v1/{externalUserId}/automation/workflows with your environment's API key instead of the user's JWT. Same body, same UUID back. Then open it with EmbeddedWorkflowBuilder and the user's token.
Production checklist
- Create a real blank workflow. Drop the hardcoded trigger.
- Build the definition with
JSON.stringify. Never interpolate user input into JSON. - Navigate to the editor with the returned UUID.
- Wrap the component in a positioned container with an explicit height.
- Refresh the token while the editor is open.
- Set
BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS. - Set
environmentexplicitly so it matches the token. - Pass
includeComponents. - Decide on connection creation in the token claim, and set the prop to match.
- Handle the
409on enable and keep the toggle disabled until the workflow has a version. - Tell users that test runs are real.
Who owns what
You own: the entry point and create dialog, the page the editor lives in, token minting and refresh, the environment, the palette, connection rules, the workflow list, enabling, and the allowed parent origins.
ByteChef owns: the editor (canvas, palette, properties, data pills, flow controls, validation), the connection picker and form, test runs, autosave, versioning, publishing, the per-user project and the engine that runs every published workflow.
Your code is a dialog, one fetch and one component. The most expensive piece of any iPaaS, the visual editor, becomes a dependency you keep current with npm update.
Try it: clone the embedded sample app, open Automations → New from Embedded Workflow Builder, give the workflow a label and click Create. Click its title, replace the trigger, add a step, hit Test, then Publish.
ByteChef is an open-source (Apache 2.0) workflow automation and AI agent platform. If this was useful, a ⭐ on GitHub helps a lot.
Next up: the Automation Hub, one embedded component that renders a complete, themed end-user automation page with your templates, the user's connections and this same builder inside it.

