StackOne Connect — Account Linking

Important

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

Instructions

Step 1: Choose a connection method

Step 2: Create a Connect Session (backend)

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"
  }'

token

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

https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session

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

references/hub-reference.md

Step 4: Set up webhook listeners

account.created

account.updated

account.deleted

https://docs.stackone.com/guides/webhooks

Step 5: Verify the connection

onSuccess

account.created

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

200

status: "active"

Examples

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

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

Example 2: User wants to send connection links via email

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)

Troubleshooting

Hub component doesn't render

• @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

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

onSuccess fires but account status is "error"

• 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

• 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