Quick Start

Create a Signing Key

Signing Keys produce an RSA keypair. The public key stays in ByteChef; the private key is shown to you once and you use it in your backend to sign JWTs that authenticate each end user into the embedded session.

1. In the ByteChef UI, go to Embedded → Settings → Signing Keys.
2. Click New Signing Key and give it a name (e.g. web-app-dev).
3. Copy the private key that's displayed — you will not see it again.
4. Note the Key Id (kid) shown in the table after the dialog closes.

You'll store the private key as a secret in your backend (e.g. BYTECHEF_SIGNING_KEY env var) and reference the kid when signing.

Create an API Key (optional, for server-to-server calls)

If your backend needs to call the embedded API on behalf of your users without minting a JWT — listing a user's integrations, managing their workflows, executing a component action — create an API Key:

1. Go to Embedded → Settings → API Keys.
2. Click New API Key, give it a name.
3. Copy the secret key — also shown only once.

Use it in an Authorization: Bearer <secret> header against the public API's /{externalUserId}-prefixed routes, e.g. GET /api/embedded/v1/{externalUserId}/integrations — with an API Key, the connected user is identified by the path segment instead of a JWT sub claim. That path segment is required: a request without it has no user to resolve and is rejected, which is why API Keys do not work on the /api/embedded/internal endpoints (including workflow executions, which live only there and are read from the ByteChef admin UI or with a Signing Key JWT).

Build and publish an Integration

1. Go to Embedded → Integrations and click New Integration.
2. Choose a component (e.g. Gmail) and give the integration a name.
3. ByteChef opens the workflow editor with a default workflow. Add triggers and actions as needed.
4. When ready, click the Publish button in the editor header, optionally add a version Description in the popover, and confirm. This creates a new version (V1 PUBLISHED).

Create an Instance Configuration

A configuration deploys a published integration version into a specific environment so connected users can activate it.

1. Go to Embedded → Integration Configurations and click New Instance Configuration.
2. Pick your integration, choose the published version, and confirm the environment.
3. Save and toggle the configuration on.

Generate a JWT for an end user

In your backend, mint a short-lived JWT for the user you want to authorize. Use RS256 and set the kid header to the Key Id from step 1.

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

const token = jwt.sign(
    {
        sub: externalUserId, // your user's unique id; ByteChef stores it as the external user 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.

Install the React SDK

npm install @bytechef/embedded

Render the Connect dialog

Hand the JWT to useConnectDialog, along with the integrationId of the configuration you want the user to connect:

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

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

    return <button onClick={openDialog}>Connect Gmail</button>;
}

When the user clicks the button, the SDK opens the ByteChef-hosted connect dialog, walks them through OAuth (or whatever the integration requires), and stores their credentials as a Connection under their Connected User record.

Trigger workflows with an App Event (optional)

If your integration's workflows use an App Event trigger, your backend fires every subscribed workflow for the connected user by POSTing to the embedded API:

POST /api/embedded/v1/app-events HTTP/1.1
Host: your-bytechef-host.example.com
Authorization: Bearer <end-user JWT>
X-Environment: DEVELOPMENT

The connected user is identified by the JWT sub claim. ByteChef looks up that user's enabled integration instances and starts an execution for every enabled workflow that carries an App Event trigger. The endpoint takes no request body and no event name, so the App Event Id selected on a trigger does not narrow the fan-out — see App Events for what that means in practice.

See App Events for how to declare event names and JSON schemas.

Inspect what happened

• Embedded → Connected Users — confirm your end user appears with the integrations they connected.
• Embedded → Connections — see the credentials they authorized.
• Embedded → Automations — view the active workflows for each user.
• Embedded → Workflow Executions — drill into every run, step by step.