stackone-connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

StackOne Connect — Account Linking

StackOne Connect — 账户关联

Important

重要说明

Before writing code, fetch the latest documentation:

Fetch

https://docs.stackone.com/guides/connect-tools-overview

for the current connection flow

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.

编写代码前，请获取最新文档：

访问

https://docs.stackone.com/guides/connect-tools-overview

获取当前连接流程

访问

https://www.npmjs.com/package/@stackone/hub

获取最新Hub组件API

Hub组件目前处于活跃测试版——不同版本间的props和peer dependencies会有所变化。

Instructions

操作步骤

Step 1: Choose a connection method

步骤1：选择连接方式

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.

方式	使用场景
嵌入式Hub（Embedded Hub）	应用内集成选择器——用户无需离开你的应用
授权链接（Auth Link）	邮件引导或外部流程——独立URL，有效期5天
控制台（Dashboard）	仅用于内部测试——切勿用于生产环境

若不确定，推荐使用嵌入式Hub，它能提供最佳用户体验。

Step 2: Create a Connect Session (backend)

步骤2：创建连接会话（后端）

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

bash

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:

json

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

你的后端需创建一个会话令牌，供前端用于初始化Hub：

bash

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

字段，请将其传递给前端。

如需筛选Hub中显示的服务商：

json

{
  "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

获取完整的请求/响应schema。

Step 3: Initialize the Hub (frontend)

步骤3：初始化Hub（前端）

bash

npm install @stackone/hub

tsx

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

bash

npm install @stackone/hub

tsx

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) => {
        // 存储account.id——后续所有API调用都需要它
        console.log("Connected:", account.id, account.provider);
      }}
      onCancel={() => console.log("User cancelled")}
      onClose={() => console.log("Hub closed")}
    />
  );
}

如需完整的props API和主题定制选项，请查阅

references/hub-reference.md

。

Step 4: Set up webhook listeners

步骤4：设置Webhook监听器

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.

Webhook是授权链接（无前端回调）的必需配置，同时也是嵌入式Hub的推荐配置：

事件	触发时机
`account.created`	新账户关联成功时
`account.updated`	凭证刷新时
`account.deleted`	账户断开关联时

访问

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

获取Webhook负载格式及设置说明。

Step 5: Verify the connection

步骤5：验证连接

After receiving

onSuccess

or the

account.created

webhook, make a test API call:

bash

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

response with

status: "active"

confirms the connection is working.

收到

onSuccess

回调或

account.created

Webhook后，发起测试API调用：

bash

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

状态码且

status: "active"

，则表明连接正常工作。

Examples

示例

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

示例1：用户希望在React应用中添加集成选择器

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

Actions:

Create a backend endpoint that calls

POST /connect_sessions

with

provider: "bamboohr"

Return the session token to the frontend

Install

@stackone/hub

and render

<StackOneHub token={token} />

Handle
```
onSuccess
```
to store the account ID
Set up a webhook endpoint for
```
account.created
```
as a backup

Result: Working integration picker that filters to BambooHR only.

用户需求：“我想让我的客户连接他们的BambooHR账户”

操作步骤：

创建后端端点，调用

POST /connect_sessions

并传入

provider: "bamboohr"

将会话令牌返回给前端

安装

@stackone/hub

并渲染

<StackOneHub token={token} />

处理
```
onSuccess
```
回调以存储账户ID
设置
```
account.created
```
Webhook端点作为备份

结果：可正常工作的集成选择器，仅显示BambooHR选项。

Example 2: User wants to send connection links via email

示例2：用户希望通过邮件发送连接链接

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

Actions:

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

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

用户需求：“我需要通过邮件引导客户，而非在应用内完成”

操作步骤：

创建连接会话，将
```
origin_owner_id
```
设置为对应客户
从会话生成授权链接（请查阅授权链接文档）
设置Webhook监听器——授权链接无前端回调
通过邮件发送链接（有效期5天）

结果：客户点击链接完成认证后，Webhook会触发并返回账户详情。

Troubleshooting

故障排查

Hub component doesn't render

Hub组件无法渲染

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

原因：缺少peer dependencies。

@stackone/hub

依赖：

react

、

react-dom

、

react-hook-form

、

@hookform/resolvers

、

zod

检查版本是否匹配——请访问NPM页面获取确切版本约束
验证会话令牌是否有效且未过期

Connect Session token expired

连接会话令牌过期

Cause: Tokens are short-lived.

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

原因：令牌有效期较短。

每次初始化Hub时生成新令牌
请勿跨会话缓存令牌

onSuccess fires but account status is "error"

onSuccess触发但账户状态为“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

原因：服务商端认证成功，但StackOne无法同步数据。

在控制台中查看账户详情以获取具体错误信息
常见原因：服务商端权限不足
服务商可能需要额外的OAuth权限范围

Webhooks not arriving

Webhook未送达

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

原因：Webhook端点配置问题。

验证端点URL是否可公开访问（不能是localhost）
检查Webhook签名密钥是否匹配

访问

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

获取验证流程