StackOne Hub (React)

Embed the native React <StackOneHub> component to let end-users connect their accounts

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

1. Install the package

   npm

   npm install @stackone/hub
   
2. 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: '[e-mail]' }),
     });
     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.

3. 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')}
       />
     );
   }
   
4. 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.