You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
fix(SOL-418): stackone-connect - update stale docs links and hub guidance
- point to embed/account-linking, connect-session, auth-link, handle-account-events
- add llms.txt + hub README fallback, web component
- drop hub-reference.md (duplicated docs)
- skill version 2.1
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
description: Implement account linking using StackOne Connect Sessions and the Hub React component. Use when user asks to "connect a provider", "embed the integration picker", "add BambooHR to my app", "create a connect session", "set up auth links", or "handle account webhooks". Covers the full flow from session creation to webhook handling. Do NOT use for making API calls after linking (use stackone-platform) or building AI agents (use stackone-agents).
3
+
description: Implement account linking using StackOne Connect Sessions and the StackOne Hub. Use when user asks to "connect a provider", "embed the integration picker", "add BambooHR to my app", "create a connect session", "set up auth links", or "handle account webhooks". Covers the full flow from session creation to webhook handling. Do NOT use for making API calls after linking (use stackone-platform) or building AI agents (use stackone-agents).
4
4
license: MIT
5
5
compatibility: Requires network access to fetch live documentation from docs.stackone.com
6
6
metadata:
7
7
author: stackone
8
-
version: "2.0"
8
+
version: "2.1"
9
9
---
10
10
11
11
# StackOne Connect — Account Linking
12
12
13
13
## Important
14
14
15
15
Before writing code, fetch the latest documentation:
16
-
1. Fetch `https://docs.stackone.com/guides/connect-tools-overview` for the current connection flow
17
-
2. Fetch `https://www.npmjs.com/package/@stackone/hub` for the latest Hub component API
16
+
1. Fetch `https://docs.stackone.com/embed/account-linking/overview.md` for the current linking flow and the ways to embed the Hub
17
+
2. Fetch `https://docs.stackone.com/embed/account-linking/stackone-hub.md` for the current `<StackOneHub>` props and theming
18
18
19
-
The Hub component is in active beta — props and peer dependencies change between versions.
19
+
The Hub component changes between versions. Take props, peer dependencies and link expiry from the docs, not from this skill.
20
+
21
+
When fetching any `docs.stackone.com` page, append `.md` to the URL to get it as markdown.
22
+
23
+
**If any URL in this skill returns 404, or a page doesn't cover what you need** (StackOne reorganizes its docs from time to time):
24
+
- Fetch `https://docs.stackone.com/llms.txt`, which indexes every docs page by title and description. Search the "Embed" section for the page's topic (e.g. "Connect Session", "Account Linking", "Auth Link", "Handle Account Events") and use the URL listed there.
25
+
- For the Hub package itself, the repository README is the fallback: `https://raw.githubusercontent.com/StackOneHQ/hub/main/README.md`.
20
26
21
27
## Instructions
22
28
23
29
### Step 1: Choose a connection method
24
30
25
31
| Method | When to use |
26
32
|--------|-------------|
27
-
|**Embedded Hub**| In-app integration picker — users stay in your app |
|**Dashboard**| Internal testing only — never for production|
33
+
|**Embedded Hub**| In-app integration picker, users stay in your app. React apps use `@stackone/hub`; other frameworks use the `<stackone-hub>` web component|
34
+
|**Auth Link**| Email onboarding, sales-led onboarding or demos. A StackOne-hosted page with the Hub already embedded, no frontend work|
35
+
|**Dashboard**| Internal tools, or linking an account on a customer's behalf|
30
36
31
37
If unsure, recommend the Embedded Hub. It provides the best user experience.
32
38
39
+
The overview page compares the methods and links to each one's guide.
40
+
33
41
### Step 2: Create a Connect Session (backend)
34
42
35
-
Your backend creates a session token that the frontend uses to initialize the Hub:
43
+
Your backend creates a session token that the frontend uses to initialize the Hub. Fetch `https://docs.stackone.com/embed/connect-session.md` for the required fields, filtering and connector profile targeting.
36
44
37
45
```bash
38
46
curl -X POST https://api.stackone.com/connect_sessions \
@@ -46,26 +54,23 @@ curl -X POST https://api.stackone.com/connect_sessions \
46
54
47
55
The response includes a `token` field. Pass this to the frontend.
48
56
49
-
To filter which providers appear in the Hub:
50
-
```json
51
-
{
52
-
"origin_owner_id": "customer-123",
53
-
"origin_owner_name": "Acme Inc",
54
-
"provider": "bamboohr",
55
-
"categories": ["hris"]
56
-
}
57
-
```
57
+
Always set `origin_owner_id` on the server. Never take it from a client request, or one customer could claim another customer's linked accounts.
58
+
59
+
To control which providers appear in the Hub, pass `provider` (opens that connector directly) or `categories` (e.g. `["hris"]`). The Connect Session page also covers `account_id`, `multiple` and `connector_profile_id`.
58
60
59
-
Fetch `https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session` for the full request/response schema.
61
+
Fetch `https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session.md` for the full request/response schema.
60
62
61
63
### Step 3: Initialize the Hub (frontend)
62
64
65
+
For React, fetch `https://docs.stackone.com/embed/account-linking/stackone-hub.md` and follow its quick start:
66
+
63
67
```bash
64
68
npm install @stackone/hub
65
69
```
66
70
67
71
```tsx
68
72
import { StackOneHub } from"@stackone/hub";
73
+
import { useEffect, useState } from"react";
69
74
70
75
function ConnectorPage() {
71
76
const [token, setToken] =useState<string>();
@@ -90,7 +95,11 @@ function ConnectorPage() {
90
95
}
91
96
```
92
97
93
-
For the full props API and theming options, consult `references/hub-reference.md`.
98
+
For the full props list and theming options, use the Properties and Theming sections of that page.
99
+
100
+
For other frameworks, fetch `https://docs.stackone.com/embed/account-linking/stackone-hub-web-component.md`.
101
+
102
+
For an Auth Link instead of an embedded Hub, fetch `https://docs.stackone.com/embed/account-linking/auth-link.md`. It covers generating the link from the dashboard or from the Connect Session response, and setting its expiry.
94
103
95
104
### Step 4: Set up webhook listeners
96
105
@@ -99,21 +108,16 @@ Webhooks are required for Auth Links (no frontend callbacks) and recommended for
99
108
| Event | When it fires |
100
109
|-------|---------------|
101
110
|`account.created`| New account linked |
102
-
|`account.updated`|Credentials refreshed |
111
+
|`account.updated`|Account changed, e.g. credentials refreshed |
103
112
|`account.deleted`| Account disconnected |
104
113
105
-
Fetch `https://docs.stackone.com/guides/webhooks` for the webhook payload format and setup instructions.
114
+
Fetch `https://docs.stackone.com/embed/handle-account-events.md` for subscribing to these events, verifying the signature and handling the payload. For webhook management in general (retries, secret rotation), fetch `https://docs.stackone.com/connect/webhooks.md`.
106
115
107
116
### Step 5: Verify the connection
108
117
109
-
After receiving `onSuccess` or the `account.created` webhook, make a test API call:
After receiving `onSuccess` or the `account.created` webhook, fetch the account and check its `status`. Fetch `https://docs.stackone.com/platform/api-reference/v2/accounts/get-an-account.md` for the endpoint and the status values.
115
119
116
-
A `200` response with `status: "active"` confirms the connection is working.
120
+
An `active`status confirms the connection is working.
117
121
118
122
## Examples
119
123
@@ -122,32 +126,34 @@ A `200` response with `status: "active"` confirms the connection is working.
122
126
User says: "I want to let my customers connect their BambooHR account"
123
127
124
128
Actions:
125
-
1. Create a backend endpoint that calls `POST /connect_sessions` with `provider: "bamboohr"`
126
-
2. Return the session token to the frontend
127
-
3. Install `@stackone/hub` and render `<StackOneHub token={token} />`
128
-
4. Handle `onSuccess` to store the account ID
129
-
5. Set up a webhook endpoint for `account.created` as a backup
129
+
1. Fetch the Connect Session and StackOne Hub (React) pages
130
+
2. Create a backend endpoint that calls `POST /connect_sessions` with `provider: "bamboohr"`
131
+
3. Return the session token to the frontend
132
+
4. Install `@stackone/hub` and render `<StackOneHub token={token} />`
133
+
5. Handle `onSuccess` to store the account ID
134
+
6. Set up a webhook endpoint for `account.created` as a backup
130
135
131
-
Result: Working integration picker that filters to BambooHR only.
136
+
Result: Working integration picker that opens straight to BambooHR.
132
137
133
138
### Example 2: User wants to send connection links via email
134
139
135
140
User says: "I need to onboard customers by email, not in-app"
136
141
137
142
Actions:
138
-
1. Create a Connect Session with `origin_owner_id` set to the customer
139
-
2. Generate an auth link from the session (fetch auth link docs)
140
-
3. Set up webhook listeners — auth links have no frontend callbacks
141
-
4. Send the link via email (valid for 5 days)
143
+
1. Fetch the Auth Link page
144
+
2. Create a Connect Session with `origin_owner_id` set to the customer, and the expiry the page describes
145
+
3. Read the auth link URL from the response, as the page describes
146
+
4. Set up webhook listeners — auth links have no frontend callbacks
147
+
5. Send the link via email
142
148
143
149
Result: Customer clicks link, authenticates, webhook fires with account details.
0 commit comments