StackOne Hub (React)

The StackOne Hub (@stackone/hub) is a native React <StackOneHub> component that renders directly in your React tree. It offers filtering, search, detailed error messages, and full theming support. It is the recommended way to implement the Hub.

Quick start

Install the package

npm install @stackone/hub

yarn add @stackone/hub

pnpm add @stackone/hub

Get a session token from your backend

The Hub needs a connect session token to securely communicate with StackOne. This token must be generated server-side to keep your API key secure.

async function retrieveConnectSessionToken() {
  const response = await fetch('/api/stackone/connect-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'jane@example.com' }),
  });
  const { token } = await response.json();
  return token;
}

To route the session through a specific connector profile (when a provider has more than one), pass its connector_profile_id when creating the session — see Target a specific connector profile.

Add the component

import { StackOneHub } from "@stackone/hub";
import { useEffect, useState } from "react";

function ConnectorPage() {
  const [token, setToken] = useState<string>();

  useEffect(() => {
    retrieveConnectSessionToken().then(setToken);
  }, []);

  if (!token) return <div>Loading...</div>;

  return (
    <StackOneHub
      token={token}
      onSuccess={(account) => {
        console.log('Connected:', account.id, account.provider);
      }}
      onCancel={() => console.log('Cancelled')}
      onClose={() => console.log('Closed')}
    />
  );
}

Let users link their accounts

Your end-users now use the Hub to connect their accounts. Each successful link fires onSuccess with the linked account id — persist against your user — it’s the account ID you’ll use with every action call.You can also capture it server-side from the account.created webhook event.

Properties

The StackOneHub component accepts these properties:

Property	Type	Default	Description
`token`	`string`	—	Connect session token from your backend
`mode`	`'integration-picker'`	`'integration-picker'`	Hub mode
`accountId`	`string`	—	Pre-select a specific account to edit
`baseUrl`	`string`	`'https://api.stackone.com'`	StackOne API base URL
`appUrl`	`string`	`'https://app.stackone.com'`	StackOne App URL
`height`	`string`	`'500px'`	Component height
`theme`	`'light' \| 'dark' \| PartialMalachiteTheme`	`'light'`	Theme configuration
`showFooterLinks`	`boolean`	`true`	Show footer links
`onSuccess`	`(account: { id: string; provider: string }) => void`	—	Called when account is connected
`onCancel`	`() => void`	—	Called when user cancels
`onClose`	`() => void`	—	Called when hub closes
`onCloseLabel`	`string`	`'Close'`	Custom label for the close button on the success screen

import { StackOneHub } from "@stackone/hub";

<StackOneHub
  token={sessionToken}
  mode="integration-picker"
  height="600px"
  theme="dark"
  showFooterLinks={false}
  onSuccess={(account) => {
    console.log(`Connected ${account.provider} with ID ${account.id}`);
  }}
  onCancel={() => console.log('User cancelled')}
  onClose={() => console.log('Hub closed')}
  onCloseLabel="Done"
/>

Use onSuccess to update your UI or trigger backend syncs. Use onClose as a cleanup handler that always runs.

Theming

The Hub supports full theming with the theme property:

<StackOneHub
  token={token}
  theme="dark"  // or "light"
/>

For custom theming, pass a PartialMalachiteTheme object:

<StackOneHub
  token={token}
  theme={{
    colors: {
      primary: {
        background: '#6366f1',
        foreground: '#ffffff',
      },
      card: {
        background: '#fafafa',
      },
    },
  }}
/>

See the @stackone/hub repository for full theme options.

For non-React stacks, use the web components build (<stackone-hub>). For the older hook API, see @stackone/react-hub on npm.

Next steps

Call Actions

With the account linked, call its actions from your product — over the Agent SDK, MCP, A2A, or RPC/HTTP.

Embed Overview

Return to the end-to-end embedding journey.

​Quick start

​Properties

​Theming

​Next steps

Call Actions

Embed Overview

Quick start

Properties

Theming

Next steps