无缝用户认证

无缝用户认证让企业合作伙伴代表自己的终端用户创建并认证 iC Candle 用户。无需让每位用户在 iC Candle 嵌入中自行注册：你的后端用邮箱换取可用的 iC Candle 会话，并把令牌直接传给组件与 API。

平台 / 经纪商子组织用户

若你是平台，要在客户 / 经纪商 identifier 下认证用户（使其出现在 manage.iccandle.site 的 Organization Users 嵌入中），请改用 平台 → 无缝认证（子组织）（get-user-token-sub-org），而不是本页。

	嵌入端登录	无缝用户认证
谁来注册	每位终端用户，在 iframe 内完成	你的系统，通过企业 API
凭证	iC Candle 账号（Google、Apple、密码）	你的企业 API 密钥
令牌来源	嵌入端的 auth.signIn postMessage	get-user-token API 响应
套餐	由终端用户自行购买	由你在控制台授予，或通过 API 批量授予

前提条件

要求	说明
企业用户	由 iC Candle 为你签发（见步骤 1）
企业控制台权限	https://corporate.iccandle.ai/
API 密钥	在控制台中生成（见步骤 3）
服务端调用方	API 密钥与生成的令牌绝不可暴露在浏览器代码中

步骤 1 — 获取企业用户

iC Candle 会为你的组织生成一个企业用户，并把凭证发给你。企业账号没有自助注册。

步骤 2 — 登录企业控制台

打开 https://corporate.iccandle.ai/，用步骤 1 收到的企业用户登录。

控制台用于管理 API 密钥、套餐余额，以及授予用户的套餐。

步骤 3 — 生成 API 密钥

在控制台中，为用户认证 API 服务生成一把 API 密钥。调用下方接口时，后端用该密钥完成认证。

打开 Create API key，选择该密钥将用于哪项服务。

保持勾选 Create as active，密钥一经签发即可使用，然后选择 Create。请立即复制密钥，并存入服务端密钥库。

密钥只放在服务端。 把 API 密钥当作密码：只从服务器调用认证 API，不要放进浏览器、移动应用，或任何发给终端用户的客户端。

步骤 4 — 获取用户令牌

速率限制与冷却

该接口每分钟最多接受 100,000 次请求。

每个用户还有 1 小时冷却：某个邮箱一旦签发过令牌，同一邮箱要再生成令牌须等一小时。

可以把收到的结果缓存起来，在 expiresIn 标明的有效期内复用 — 不适合在应用的每次请求都调用该接口。

POST https://api.iccandle.ai/seamless-auth/get-user-token
x-api-key: <your-api-key>
Content-Type: application/json

请求体：

{
  "email": "test@email.com"
}

响应：

{
  "email": "test@email.com",
  "created": true,
  "idToken": "",
  "accessToken": "",
  "refreshToken": "",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}

TypeScript 类型：

type UserTokenResponse = {
  email: string;
  created: boolean;
  idToken?: string;
  accessToken?: string;
  refreshToken?: string;
  expiresIn: number;
  tokenType: "Bearer";
};

字段	类型	说明
email	string	该会话所属邮箱
created	boolean	本次请求为该邮箱新建了 iC Candle 用户时为 true
idToken	string	用户身份令牌
accessToken	string	调用 iC Candle API 所用令牌
refreshToken	string	当前会话过期后用于换取新会话
expiresIn	number	会话有效期（秒）（86400 = 24 小时）
tokenType	string	始终为 Bearer

调用示例：

curl -X POST \
  https://api.iccandle.ai/seamless-auth/get-user-token \
  -H "x-api-key: $ICCANDLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@email.com"}'

步骤 5 — 让用户登录组件

拿到 get-user-token 的令牌后，用这些令牌作为查询参数加载嵌入页 /{locale}/sign-in。嵌入端会据此建立会话 — 终端用户不必再走 Google、Apple 或密码表单。

从你的后端调用 POST https://api.iccandle.ai/seamless-auth/get-user-token。把返回的令牌传给宿主页，再设置 iframe 的 src。不要把 API 密钥写进浏览器代码。

若会话已存在则跳过该请求。使用 useICCandleAuth() — 若 isAuthenticated 为 true，复用现有会话。这样可避免步骤 4 中每个邮箱 1 小时的冷却。

1. 用 useICCandleAuth() 检查认证。若 isAuthenticated 为 true，让 iframe 留在 /{locale}?theme=…&header=…，不要调用 API。
2. 仅当 isAuthenticated 为 false 时 生成令牌。由你的后端把终端用户邮箱 POST 到 get-user-token。
3. 确认 idToken、accessToken 与 refreshToken 均已返回。
4. 将这些令牌映射为查询参数，把 iframe 设为 /{locale}/sign-in。

认证流程

务必先检查认证，再生成令牌。若 isAuthenticated 已为 true，复用会话，iframe 留在 /{locale}。对仍有有效令牌的邮箱调用 get-user-token 没有必要，还可能触发步骤 4 的 1 小时冷却。

组件实现：

• ReactJS 组件 → 无缝认证示例
• VueJS 组件 → 无缝认证示例

从你的后端调用 POST https://api.iccandle.ai/seamless-auth/get-user-token，并带上企业 API 密钥。不要把该密钥放进宿主页。

查询参数	API 响应字段	必需
id_token	idToken	是
access_token	accessToken	是
refresh_token_param	refreshToken	是
theme	light、dark 或 system	否
header	true 显示嵌入顶栏，false 隐藏	否

刷新令牌必须用 refresh_token_param 传递，不能用 refresh_token。

在 expiresIn 到期前，对同一邮箱再次调用 get-user-token 可换取新会话。因为有 1 小时冷却，应提前申请新令牌，不要等到旧令牌刚好过期。

步骤 6 — 在控制台管理套餐与余额

在 https://corporate.iccandle.ai/ 你可以：

• 向用户授予套餐。
• 为套餐余额充值。
• 查看剩余余额。
• 查看交易记录。

步骤 7 — 批量授予套餐

要一次给多名用户授予积分套餐，请使用批量接口，而不是控制台。

POST https://api.iccandle.ai/corporate-client/v1/bundle/plan/bulk
x-api-key: <your-api-key>
Content-Type: application/json

请求体：

{
  "emails": ["test1@email.com", "test2@email.com"],
  "plan": "pro"
}

字段	类型	说明
emails	string[]	接收套餐的用户邮箱
plan	string	要授予的套餐，例如 pro

授予套餐会扣减套餐余额，大批量授予前请先在控制台充值。

典型流程

1. iC Candle 签发你的企业用户。
2. 你登录企业控制台并生成 API 密钥。
3. 用 React 或 Vue 组件的 useICCandleAuth() 检查认证。若 isAuthenticated 为 true，跳过接下来两步。
4. 否则由后端携带终端用户邮箱调用 get-user-token。
5. 用 id_token、access_token 与 refresh_token_param 加载 /{locale}/sign-in，或把 accessToken 作为 Bearer 令牌调用 iC Candle API。
6. 在控制台为用户授予套餐，或通过套餐 API 批量授予。