> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connection Methods

> Choose the right method to connect your end-users' accounts

StackOne offers three ways to let end-users connect their accounts to your application.

| Method                              | Best For           | User Experience |
| ----------------------------------- | ------------------ | --------------- |
| **[Embedded Hub](#embedded-hub)**   | Production apps    | In-app, branded |
| **[Auth Link](#auth-link)**         | Email flows, demos | Standalone page |
| **[Dashboard](#dashboard-linking)** | Internal testing   | Admin-only      |

## Embedded Hub

Embed the StackOne Hub directly in your app. End-users select a connector and authenticate without leaving your application.

<Tabs>
  <Tab title="Use Cases">
    * Production applications with custom UX
    * Branded, in-app connection experience
    * Full control over the integration flow
  </Tab>

  <Tab title="How It Works">
    1. Backend generates a [Connect Session token](/platform/api-reference/connect-sessions/create-connect-session)
    2. Frontend initializes the Hub with the token
    3. End-user selects provider and authenticates
    4. StackOne creates linked account and fires webhook
  </Tab>
</Tabs>

<Card title="Embedding Guide →" icon="window" href="/guides/embedding-stackone-hub">
  Complete guide for React and non-React implementations
</Card>

## Auth Link

Secure URLs that open the StackOne Hub in a standalone browser tab. Generate from the dashboard or via API.

<Tabs>
  <Tab title="Use Cases">
    * Onboarding emails asking end-users to connect their HRIS
    * Quick demos without frontend integration work
    * Sales-led onboarding flows
  </Tab>

  <Tab title="How It Works">
    1. Generate link from [dashboard](https://app.stackone.com/accounts) or [API](/platform/api-reference/connect-sessions/create-connect-session)
    2. Send link to end-user (valid 5 days by default)
    3. End-user clicks, authenticates
    4. StackOne creates linked account and fires webhook
  </Tab>
</Tabs>

<Card title="Auth Links Guide →" href="/guides/auth-link" />

<Tip>
  To trigger a workflow when an account is linked via Auth Link, subscribe to [account webhooks](#webhooks) since there's no frontend callback available.
</Tip>

## Dashboard Linking

Connect accounts directly from the StackOne dashboard for internal testing.

<Tabs>
  <Tab title="Use Cases">
    * Testing API integration during development
    * Debugging connection issues
    * Internal demos
  </Tab>

  <Tab title="How It Works">
    1. Go to [Accounts](https://app.stackone.com/accounts)
    2. Click **Link Account**
    3. Select provider and enter credentials
    4. Use resulting `account_id` in API calls
  </Tab>
</Tabs>

<Warning>
  Dashboard linking is for internal use only. End-users should use the Embedded Hub or Auth Links.
</Warning>

***

## Connection Events

Get notified when accounts are connected, updated, or disconnected.

### Frontend Callbacks (Embedded Hub)

When using the Embedded Hub, handle connection events directly in your frontend:

<Tabs>
  <Tab title="Hub">
    ```tsx theme={null}
    import { StackOneHub } from "@stackone/hub";

    function App() {
      return (
        <StackOneHub
          onSuccess={(account) => {
            console.log('Account linked:', account.id);
            // Trigger your onboarding flow
          }}
          onCancel={() => console.log('User cancelled')}
          onClose={() => console.log('Hub closed')}
        />
      );
    }
    ```
  </Tab>

  <Tab title="Legacy Hub">
    ```tsx theme={null}
    import { useStackOneHub } from '@stackone/react-hub';

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

      const startFlow = async () => {
        const { token } = await retrieveConnectSessionToken();
        startConnect({
          sessionToken: token,
          onSuccess: (account) => {
            console.log('Account linked:', account.id);
          },
          onCancel: () => console.log('User cancelled'),
        });
      };

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

### Webhooks

For backend notifications (required for Auth Links, recommended for all methods), subscribe to account webhooks:

| Event             | Triggered When                            |
| ----------------- | ----------------------------------------- |
| `account.created` | New account linked                        |
| `account.updated` | Account credentials refreshed or modified |
| `account.deleted` | Account disconnected                      |

```json Example webhook payload theme={null}
{
  "event": "account.created",
  "data": {
    "id": "acme-corp-bamboohr",
    "provider": "bamboohr",
    "origin_owner_id": "cust_12345",
    "status": "active"
  }
}
```

<CardGroup cols={1}>
  <Card title="Webhooks Guide" icon="bell" href="/guides/webhooks">
    Full setup and event reference
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Embed the Hub" icon="window" href="/guides/embedding-stackone-hub">
    Full guide for React and script embedding
  </Card>

  <Card title="Auth Links" icon="link" href="/guides/auth-link">
    Generate and send connection links
  </Card>

  <Card title="Managing Accounts" icon="users" href="/guides/accounts-section">
    View and manage connected accounts
  </Card>

  <Card title="Backend Setup" icon="server" href="/platform/connect-your-backend-with-stackone">
    Generate session tokens securely
  </Card>
</CardGroup>