stackonehq/stackone-connect

StackOne Connect — Account Linking

Important

Before writing code, fetch the latest documentation:

1. Fetch https://docs.stackone.com/guides/connect-tools-overview for the current connection flow
2. Fetch https://www.npmjs.com/package/@stackone/hub for the latest Hub component API

The Hub component is in active beta — props and peer dependencies change between versions.

Instructions

Step 1: Choose a connection method

| Method | When to use | |--------|-------------| | Embedded Hub | In-app integration picker — users stay in your app | | Auth Link | Email onboarding or external flows — standalone URL, valid 5 days | | Dashboard | Internal testing only — never for production |

If unsure, recommend the Embedded Hub. It provides the best user experience.

Step 2: Create a Connect Session (backend)

Your backend creates a session token that the frontend uses to initialize the Hub:

curl -X POST https://api.stackone.com/connect_sessions \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_owner_id": "customer-123",
    "origin_owner_name": "Acme Inc"
  }'

The response includes a token field. Pass this to the frontend.

To filter which providers appear in the Hub:

{
  "origin_owner_id": "customer-123",
  "origin_owner_name": "Acme Inc",
  "provider": "bamboohr",
  "categories": ["hris"]
}

Fetch https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session for the full request/response schema.

Step 3: Initialize the Hub (frontend)

npm install @stackone/hub

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

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

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

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

  return (
    <StackOneHub
      token={token}
      onSuccess={(account) => {
        // Store account.id — you'll need it for all subsequent API calls
        console.log("Connected:", account.id, account.provider);
      }}
      onCancel={() => console.log("User cancelled")}
      onClose={() => console.log("Hub closed")}
    />
  );
}

For the full props API and theming options, consult references/hub-reference.md.

Step 4: Set up webhook listeners

Webhooks are required for Auth Links (no frontend callbacks) and recommended for the Embedded Hub:

| Event | When it fires | |-------|---------------| | account.created | New account linked | | account.updated | Credentials refreshed | | account.deleted | Account disconnected |

Fetch https://docs.stackone.com/guides/webhooks for the webhook payload format and setup instructions.

Step 5: Verify the connection

After receiving onSuccess or the account.created webhook, make a test API call:

curl https://api.stackone.com/accounts/{account_id} \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)"

A 200 response with status: "active" confirms the connection is working.

Examples

Example 1: User wants to add an integration picker to a React app

User says: "I want to let my customers connect their BambooHR account"

Actions:

1. Create a backend endpoint that calls POST /connect_sessions with provider: "bamboohr"
2. Return the session token to the frontend
3. Install @stackone/hub and render <StackOneHub token={token} />
4. Handle onSuccess to store the account ID
5. Set up a webhook endpoint for account.created as a backup

Result: Working integration picker that filters to BambooHR only.

Example 2: User wants to send connection links via email

User says: "I need to onboard customers by email, not in-app"

Actions:

1. Create a Connect Session with origin_owner_id set to the customer
2. Generate an auth link from the session (fetch auth link docs)
3. Set up webhook listeners — auth links have no frontend callbacks
4. Send the link via email (valid for 5 days)

Result: Customer clicks link, authenticates, webhook fires with account details.

Troubleshooting

Hub component doesn't render

Cause: Missing peer dependencies.

• @stackone/hub requires: react, react-dom, react-hook-form, @hookform/resolvers, zod
• Check that versions match — fetch the NPM page for exact version constraints
• Verify the session token is valid and not expired

Connect Session token expired

Cause: Tokens are short-lived.

• Generate a new token for each Hub initialization
• Do not cache tokens across sessions

onSuccess fires but account status is "error"

Cause: Provider-side authentication succeeded but StackOne couldn't sync data.

• Check the account details in the dashboard for the specific error
• Common cause: insufficient permissions on the provider side
• The provider may require additional OAuth scopes

Webhooks not arriving

Cause: Webhook endpoint configuration issue.

• Verify the endpoint URL is publicly accessible (not localhost)
• Check the webhook signing secret matches
• Fetch https://docs.stackone.com/guides/webhooks for the verification process