Installing the SDK

Install the @bytechef/embedded React SDK and authenticate your end users with signed JWTs.

The @bytechef/embedded SDK renders ByteChef's embedded surfaces - the Connect dialog, the Automation Hub, the Integration Marketplace and the embedded workflow builder - inside your own product. This page covers installing the package and wiring up end-user authentication.

Installing from npm

npm install @bytechef/embedded

The package (version 0.4.0) exports these surfaces:

useConnectDialog - a React hook that opens the hosted Connect dialog so an end user can authorize an integration.
AutomationHub - a React component that embeds the Automation Hub, a catalog of automation templates the end user activates, with tabs, an activation dialog and a theme prop.
useActivationDialog and ActivationDialog - a hook and a component that open the activation dialog from your own page, so a connected user can connect accounts, fill in inputs and turn on a published template.
IntegrationMarketplace - a React component that embeds the Integration Marketplace, an integration catalog that opens the Connect dialog in your page.
EmbeddedWorkflowBuilder - a React component that embeds the workflow editor so end users can build their own automations.

The package also exports the AutomationHubTabsConfig and AutomationHubTheme types for the hub's tabs and theme props, and the ActivationDialogProps and UseActivationDialogProps types.

The surfaces are configured with the same three values: your ByteChef instance's baseUrl, an environment (DEVELOPMENT, STAGING, or PRODUCTION), and a jwtToken identifying the current end user.

Upgrading to 0.4.0

sharedConnectionIds is removed from AutomationHub and EmbeddedWorkflowBuilder. It had no effect - the server never added the connections it named. Connected users see their own connections plus the ones a tenant admin marks as shared. Delete the prop from your code.
EmbeddedWorkflowBuilder now loads workflow-builder.html#/embedded/builder/:workflowUuid. Iframes created by 0.3.0 and earlier that still point at /embedded/workflow-builder/:workflowUuid are redirected there.

Setup

ByteChef needs to know which of your users is interacting with the embedded surface. You prove this with a short-lived JWT that your backend signs with a private key only you hold - ByteChef verifies it with the matching public key and resolves (or creates) the Connected User identified by the token's sub claim.

Create a Signing Key

In the ByteChef UI, go to Embedded → Settings → Signing Keys.
Click New Signing Key and give it a name (e.g. web-app-dev).
Copy the private key shown in the dialog - it is displayed only once. Store it as a secret in your backend (e.g. a BYTECHEF_SIGNING_PRIVATE_KEY environment variable).
Note the Key Id (kid) shown in the table - you set it as the JWT's kid header so ByteChef knows which public key to verify with.

Keep the private key server-side

The private key must never reach the browser. Your backend signs tokens; your frontend only ever sees the resulting short-lived JWT.

Generate a user token in your backend

Sign an RS256 JWT whose sub claim is your user's unique id. ByteChef stores this value as the Connected User's external user id - every connection and workflow the user activates hangs off it.

// Node.js example using jsonwebtoken
import jwt from 'jsonwebtoken';

const token = jwt.sign(
    {
        sub: externalUserId, // your user's unique id
        iat: Math.floor(Date.now() / 1000),
    },
    process.env.BYTECHEF_SIGNING_PRIVATE_KEY!,
    {
        algorithm: 'RS256',
        expiresIn: '10m',
        keyid: process.env.BYTECHEF_SIGNING_KEY_ID!,
    }
);

Keep the TTL short (10 minutes is a good default) and mint a fresh token per session. A common pattern is a small authenticated endpoint (e.g. POST /api/token) that returns a token for the logged-in user - the Sample App implements exactly this with Fastify.

Pass the token to the SDK

There is no global authenticate() call - each SDK surface takes the JWT directly:

'use client';
import {useConnectDialog} from '@bytechef/embedded';

const {openDialog} = useConnectDialog({
    baseUrl: 'https://your-bytechef-host.example.com',
    environment: 'DEVELOPMENT',
    integrationId,
    jwtToken,
});

The same jwtToken also authenticates direct calls to the embedded REST API (Authorization: Bearer <token> plus an X-Environment header) - for example GET /api/embedded/v1/integrations to list the integrations available to that user.

Next step

With the SDK installed and tokens flowing, add an integration for your users to connect.