StackOne Hub UI

The StackOne Hub lets end-users authenticate and configure connectors enabled in your StackOne projects.

Choosing a Hub Version

StackOne offers two Hub versions. We recommend the Hub for new projects. The Legacy Hub remains available for existing implementations.

	Hub	Legacy Hub
Package	`@stackone/hub`	`@stackone/react-hub` / `connect.js`
Architecture	Native React component	Iframe-based (loads external script)
React Support	Yes	Yes
Non-React Support	Yes (web component)	Yes (`connect.js`)
Filtering & Search	Yes	No
Error Messages	Detailed with resolution steps	Basic
Theming	Full theming via design system	Limited styling options
Performance	Fast (direct API calls)	Average (iframe network hops)
Status	Recommended	Legacy

Why the Hub?

The Hub is a ground-up rebuild with a fundamentally different architecture:

Native React Component: The Hub renders directly in your React tree. The Legacy Hub loads an external script (connect.js) that injects an iframe. This means the Hub shares your app’s React context, supports proper component composition, and eliminates iframe-related overhead.
Direct API Communication: The Hub makes API calls directly from your app. The Legacy Hub routes requests through an iframe hosted on StackOne’s domain, adding latency from cross-origin communication and extra network hops.
Full Theming Support: The Hub uses our Malachite design system, giving you complete control over colors, typography, and styling. You can match your app’s design without CSS hacks or iframe styling limitations.
Better Event Handling: The Hub uses native React callbacks. The Legacy Hub relies on postMessage to communicate events across the iframe boundary, which can be less reliable and harder to debug.

Quick Start

Hub - React
Legacy Hub - React
Legacy Hub - Vanilla JS
Web Component

The Hub (@stackone/hub) offers filtering, search, detailed error messages, and full theming support.

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;
}

See Connect your Backend with StackOne for backend implementation.

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

The Legacy Hub. For new projects, use the Hub above.

The Legacy Hub (@stackone/react-hub) provides a hook-based API.

Install the package

npm install @stackone/react-hub

yarn add @stackone/react-hub

pnpm add @stackone/react-hub

Create a function to retrieve the session token

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.

export const retrieveConnectSessionToken = async ({ username, provider }) => {
  const response = await fetch('/api/stackone/connect-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      originUsername: username,
      provider, // optional - skip connector listing
    }),
  });

  const { token } = await response.json();
  return { token };
};

See Connect your Backend with StackOne for backend implementation.

Create a Link Account Button

import { useCallback } from 'react';
import { useStackOneHub } from '@stackone/react-hub';

const LinkAccountButton = () => {
  const { startConnect } = useStackOneHub();

  const startFlow = useCallback(async () => {
    const { token } = await retrieveConnectSessionToken({
      username: 'jane@example.com'
    });
    startConnect({
      sessionToken: token,
      onSuccess: (account) => {
        console.log('Account linked:', account);
      },
      onCancel: () => console.log('Cancelled'),
      onClose: () => console.log('Closed'),
    });
  }, [startConnect]);

  return <button onClick={startFlow}>Connect Account</button>;
};

The Legacy Hub. The Hub doesn’t yet support vanilla JS. For non-React apps, use connect.js below or generate Auth Links from the dashboard.

The Legacy Hub provides connect.js, a standalone JavaScript library for non-React applications.

Install the connect script

<script src="https://app.stackone.com/stackone/connect.js"></script>

const script = document.createElement('script');
script.src = 'https://app.stackone.com/stackone/connect.js';
script.onload = () => {
  // Connect is now available globally
  console.log('Connect.js loaded');
};
document.body.appendChild(script);

Create a function to retrieve the session token

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' }),
  });
  return response.json();
}

See Connect your Backend with StackOne for backend implementation.

Start the connect flow

const { token } = await retrieveConnectSessionToken();

Connect.start({
  sessionToken: token,
  onSuccess: (account) => {
    console.log('Account linked:', account);
  },
  onCancel: () => {
    console.log('User cancelled');
  },
  onClose: () => {
    console.log('Hub closed');
  },
});

@stackone/hub also ships a framework-agnostic custom element (<stackone-hub>) for non-React apps. React + ReactDOM are bundled into the web-component build, so consumers don’t need React installed.Pick the framework guide that matches your stack:

Vanilla HTML

Drop a <script> tag into any HTML page.

Vue 3

Configure isCustomElement and use the tag in templates.

Svelte 5

No extra config — Svelte treats unknown tags as custom elements.

Angular

Use CUSTOM_ELEMENTS_SCHEMA and bind attributes with [attr.name].

React

Mount <stackone-hub> from JSX when you need the framework-agnostic build.

API Reference

Hub - @stackone/hub
Legacy Hub - @stackone/react-hub
Legacy Hub - connect.js

The StackOneHub component accepts these props:

Prop	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"
/>

The useStackOneHub hook returns a startConnect function:

const { startConnect } = useStackOneHub({ connectUrl?: string });

StartOptions

Option	Type	Required	Description
`sessionToken`	`string`	Yes	Connect session token from your backend
`apiUrl`	`string`	No	Custom API URL
`styles`	`HubStyles`	No	Style customization
`onSuccess`	`(account: Account) => void`	No	Called when account is connected
`onCancel`	`() => void`	No	Called when user cancels
`onClose`	`() => void`	No	Called when hub closes

import { useStackOneHub } from '@stackone/react-hub';

const { startConnect } = useStackOneHub();

startConnect({
  sessionToken: token,
  onSuccess: (account) => {
    console.log('Connected account:', account.id);
  },
  onCancel: () => console.log('Cancelled'),
  onClose: () => console.log('Closed'),
});

After loading the script, use the global Connect object:

Connect.start({
  sessionToken: string,     // Required - from your backend
  apiUrl?: string,          // Optional - custom API URL
  styles?: HubStyles,       // Optional - style customization
  onSuccess?: (account) => void,
  onCancel?: () => void,
  onClose?: () => void,
});

Full example:

Connect.start({
  sessionToken: token,
  styles: {
    inline: { containerId: 'hub-container', width: '100%', height: '600px' },
    options: { back: true, close: true, bgColor: '#f5f5f5' },
  },
  onSuccess: (account) => {
    console.log('Account linked:', account);
    // account has: id, provider, status, etc.
  },
  onCancel: () => {
    console.log('User cancelled the flow');
  },
  onClose: () => {
    console.log('Hub modal was closed');
  },
});

Style Customization

Hub
Legacy Hub

The Hub supports full theming with the theme prop:

<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.

The Legacy Hub uses a styles object with two sections:

HubStyles Interface

interface HubStyles {
  inline?: {
    containerId: string;  // Required - DOM element ID to embed the hub
    width?: string;       // e.g., '400px', '100%'
    height?: string;      // e.g., '500px', '100%'
  };
  options?: {
    back?: boolean;       // Show/hide back arrow (default: true)
    close?: boolean;      // Show/hide close button (default: true)
    bgColor?: string;     // Background color (e.g., 'white', '#f0f0f0')
  };
}

Default (Modal) - Hub opens in a centered modal overlay:

startConnect({ sessionToken: token });

Inline - Hub embeds in a specific container:

startConnect({
  sessionToken: token,
  styles: {
    inline: {
      containerId: 'my-hub-container',
      width: '400px',
      height: '600px',
    },
    options: {
      back: false,
      close: false,
      bgColor: 'transparent',
    },
  },
});

Hub Behavior Customization

Control which connectors appear in the Hub by configuring the connect session on your backend.

Filtering Connectors

You can specify a provider or categories property when creating the connect session to control which connectors appear in the Hub:

provider: Opens the Hub directly at the credential entry screen for a specific connector, bypassing the connector listing
categories: Filters the Hub to show only connectors from specified categories (e.g., hris, ats)

If neither is specified, the Hub displays all connectors enabled for the project.

The connector specified in provider must be enabled in the Connector Profiles page of the associated project.

Find valid provider keys in the Supported Connectors list under the Provider Key column.

Backend Examples

// Skip connector list, go directly to BambooHR
const result = await stackOne.connectSessions.createConnectSession({
  originOwnerId: "customer-123",
  originOwnerName: "Acme Inc",
  provider: "bamboohr",  // Go directly to this connector
});

// Show only HRIS connectors
const result = await stackOne.connectSessions.createConnectSession({
  originOwnerId: "customer-123",
  originOwnerName: "Acme Inc",
  categories: ["hris"],  // Filter to HRIS category
});

Event Callbacks

All Hub versions support these callbacks:

Callback	When it fires
`onSuccess`	User successfully connects an account. Receives account object with `id` and `provider`.
`onCancel`	User explicitly cancels the flow (clicks cancel/back).
`onClose`	Hub closes for any reason (success, cancel, or clicking outside modal).

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

startConnect({
  sessionToken: token,
  onSuccess: (account) => {
    // Refresh your linked accounts
    fetchLinkedAccounts();
    showNotification(`Connected to ${account.provider}`);
  },
  onCancel: () => {
    // User backed out - maybe show a prompt
    console.log('Connection cancelled');
  },
  onClose: () => {
    // Always runs - cleanup
    setIsConnecting(false);
  },
});

Dashboard Access

You can also use the Hub directly from the StackOne dashboard without embedding:

Connection Links

Generate connection links from your dashboard to share with end-users.

Dashboard Connection Link Generation

Direct Account Linking

Link accounts directly from the dashboard interface.

Dashboard Account Linking

Backend Setup

Both hub versions require a connect session token generated from your backend. This keeps your API key secure.

Backend Implementation

Generate session tokens securely from your backend

API Reference

Connect Sessions endpoint documentation

Quickstart

Connect Tools

Dashboard

Build Connectors

Choosing a Hub Version

Why the Hub?

Quick Start

Vanilla HTML

Vue 3

Svelte 5

Angular

React

API Reference

Style Customization

HubStyles Interface

Hub Behavior Customization

Filtering Connectors

Backend Examples

Event Callbacks

Dashboard Access

Connection Links

Direct Account Linking

Backend Setup

Backend Implementation

API Reference

​Choosing a Hub Version

​Why the Hub?

​Quick Start

Vanilla HTML

Vue 3

Svelte 5

Angular

React

​API Reference

​Style Customization

​HubStyles Interface

​Default (Modal) vs Inline

​Hub Behavior Customization

​Filtering Connectors

​Backend Examples

​Event Callbacks

​Dashboard Access

​Connection Links

​Direct Account Linking

​Backend Setup

Backend Implementation

API Reference

Choosing a Hub Version

Why the Hub?

Quick Start

API Reference

Style Customization

HubStyles Interface

Default (Modal) vs Inline

Hub Behavior Customization

Filtering Connectors

Backend Examples

Event Callbacks

Dashboard Access

Connection Links

Direct Account Linking

Backend Setup