INTEGRATION GUIDE

把一次验证接入你的站点

每个业务站点拥有独立的 siteKey 和绑定域名。服务端结合会话状态、一次性凭证与风险策略保护关键流程；成功响应只返回短时 verification ticket。

01 / QUICK START

快速开始

在管理后台使用管理员 token 创建站点，记录返回的 siteKey。演示环境默认站点也可通过 GET /api/sites 查看。

GET /api/sites

{
  "ok": true,
  "sites": [{ "id": "portal", "name": "企业门户", "siteKey": "sl_portal_8f1a4c2d" }],
  "challengeType": "shieldlab_checkbox"
}

站点 key 只用于选择业务站点，不是管理员凭证。管理员接口必须使用 Authorization: Bearer <admin token>。

02 / SDK RENDER

只配置 siteKey，直接渲染 TRUSTTURN UI

对接方不需要复制验证码结构或维护安全逻辑。加载 TRUSTTURN SDK 后传入自己的站点 key，组件界面、环境校验、challenge、verify 和过期刷新均由服务统一完成。

<div id="trustturn-box"></div>
<script src="https://cdn.trustturn.cc/a4c9d270.js"></script>
<script>
  TrustTurn.render('#trustturn-box', {
    siteKey: 'sl_portal_8f1a4c2d',
    onSuccess(ticket) {
      console.log(ticket.verificationTicket);
    }
  });
</script>

SDK iframe 始终从 TRUSTTURN 服务端加载原生 UI；默认保留完整成功态 800ms 后再触发成功回调。对接页面只负责提供容器、siteKey 和业务请求；如需调整，可传入 successDisplayMs（0 至 5000 毫秒）。

03 / SESSION

创建会话

GET/api/session/bootstrap

首次访问会设置 HttpOnly sl_session Cookie，并建立本次验证会话。后续请求需要携带同一 Cookie、User-Agent 和出口地址。

const bootstrap = await fetch('https://api.trustturn.cc/api/session/bootstrap', {
  credentials: 'include'
}).then(r => r.json());
// SDK 使用 bootstrap.sessionCrypto 建立本次验证会话

04 / CHALLENGE

签发一次性 challenge

POST/api/challenge

前端在用户明确同意后采集最小必要信号，生成受保护的 wlzData 并提交 challenge。对接方只需要透传 SDK 生成的载荷。

await fetch('https://api.trustturn.cc/api/challenge', {
  method: 'POST', credentials: 'include',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ wlzData })
});

响应中的 wsToken 是短时、绑定会话和站点的一次性凭证，只能提交一次；同时返回 challenge 标识和完整性字段，这些字段都必须原样带回 verify。

05 / VERIFY

提交 verify 并取得 ticket

POST/api/verify/

验证范围按当前站点的 siteId 生成。前端提交受保护的 verify 载荷，服务端会检查站点、域名、会话和凭证是否一致。

{
  "securePayload": "<SDK 生成的受保护载荷>"
}

// 成功响应
{ "success": true, "site_id": "portal",
  "verification_ticket": "短时 ticket", "message": "验证成功" }

06 / LOGIN

把 ticket 交给业务登录

POST/api/login

{
  "username": "demo",
  "password": "demo123",
  "verification_ticket": "<ticket>",
  "site_key": "<siteKey>"
}

ticket 默认 60 秒有效且只能消费一次；登录接口会再次校验当前会话与 siteKey。

07 / OPERATIONS

错误码与运行边界

challenge_binding：验证凭证与当前站点不一致。
replayed_token：一次性凭证已使用。
expired_token：验证超时，组件会自动重新初始化。
site_domain_not_allowed：当前域名未绑定到该站点。
site_authorization_expired：站点业务授权已到期。
site_authorization_frozen：站点业务授权已冻结。
site_authorization_revoked：站点业务授权已吊销。
session_binding：当前会话环境发生变化。
environment_risk：当前访问环境未通过风险校验。
invalid_verification：登录凭证无效、过期或已消费。

管理员可以在后台配置站点域名、授权范围和风险策略，并查看验证事件。正式部署前请配置管理员强认证、访问审计、数据保留周期与适用的告知机制。