嵌入令牌与用户

嵌入令牌让终端用户访问指定智能体及自己名下的会话。登录用户的令牌由宿主后端签发，浏览器消费；本页说明身份、有效期、刷新和单张令牌吊销。

准备同组织的服务智能体、已保存的嵌入策略和服务端 API Key。策略在控制台的接入与配置 → 配置 → 安全保存，目前只能在控制台配置。示例使用 Develop；完整网页接入见嵌入到网页，一次性跳转见 Hosted。

身份与访问范围

宿主后端用自己的登录系统确认用户，再以 external_user_id 传入稳定标识。同一组织、同一智能体、同一标识对应同一个终端用户；它不是组织成员 ID，也不是昵称。标识长 1–128 字符，仅允许字母、数字、下划线、点、冒号、@ 和连字符。

刷新令牌不会改变用户身份。更换登录账户则应移除旧组件，按新身份重新创建；界面中的确认按钮不能代替工具服务端的账户授权。

签发令牌

生产签发由宿主后端调用 POST /agent/v1/embed_tokens。以下是服务端独立检查，测试用户固定为 customer_123；真实宿主必须从验证后的登录会话取值，不接受浏览器自报身份。控制台的试用调试 → 模拟 → 重新签发只用于调试身份。

set -o pipefail
curl --fail-with-body --silent --show-error \
  -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"agent":"agent_REPLACE_ME","external_user_id":"customer_123"}' \
  | jq '{id, expires_at, has_token: (.token | type == "string")}'

期望：HTTP 201，响应含 id、token、expires_at。id 标识本次签发，供后续吊销；token 是浏览器凭证；expires_at 是 ISO 8601 UTC 到期时间。示例只输出脱敏检查结果。每次调用都会新建签发记录，重复请求不幂等。

可选 ttl_seconds 省略时取策略默认值；范围从 60 秒到策略上限与 3600 秒中的较小值。budget_cents 不能超过策略单会话预算上限；allowed_origins 只能取策略已有条目的子集。版本按显式 version、策略固定版本、最新版本的次序选择，签发后固定。完整字段见 API 参考。

刷新与结束访问

Kit 调用 getToken(current) 时，首次传入 null，刷新时传入当前令牌。把以下回调放进快速开始的 api.getToken；宿主端点每次都验证用户仍已登录，再返回新令牌。

async function getToken(current) {
  const response = await fetch("/api/praxis-token", {
    method: "POST", credentials: "same-origin", cache: "no-store",
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);
  const data = await response.json();
  if (typeof data.token !== "string" || !data.token) throw new Error("Missing token");
  return data.token;
}

回调不需要把当前令牌发回宿主来证明身份。Kit 负责调用时机并在内存中持有令牌；不要把一个固定令牌写死在回调中。期望：刷新后仍访问同一用户的会话。

宿主退出登录时，先结束宿主会话，再移除旧 Kit 元素；移除会关闭它的连接，但不会在服务器吊销已签发的令牌。需要立即禁止原凭证访问时，另行吊销。Hosted 没有这条刷新路径，到期后必须回宿主重新进入。

匿名访客

公开问答不要求登录时，在接入与配置 → 密钥 → 可公开 key → 新建可公开 key创建 key，设置匿名限流和预算，并复制只显示一次的完整值。来源仍在配置 → 安全管理。这些设置目前只能在控制台配置；可公开 key 与服务端 API Key 不能互换。

以下是可独立保存的 index.html。替换 PRAXIS_PUBLISHABLE_KEY 为实际可公开 key，并从允许来源的网站提供此文件。它不需要登录用户的宿主签发端点；不要同时配置 getToken。

<!doctype html>
<html lang="zh">
<meta charset="utf-8">
<title>Public documentation assistant</title>
<script type="module" src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js" integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU" crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<script type="module">
  await customElements.whenDefined("praxis-agent");
  document.querySelector("praxis-agent").setOptions({
    api: {
      url: "https://api-develop.deepraxis.com",
      publishableKey: "PRAXIS_PUBLISHABLE_KEY",
    },
    agent: { name: "Documentation assistant" },
  });
</script>
</html>

Kit 向 POST /agent/v1/embed_tokens/anonymous 提交 publishable_key，后续带上已有的 visitor_secret。接口不需要 API Key，成功返回 HTTP 200、token、expires_at；仅新访客另收到 visitor_secret。浏览器不能选择 external_user_id、预算、指令或 Hosted 选项。

Kit 将访客凭据保存在本地存储，存储不可用时退回页面内存。不要公开或共享它。期望：同一存储中的访客刷新后延续身份；独立浏览器存储产生独立身份。匿名身份不授予读取实名订单等账户数据的权限。

查看与吊销

只吊销需要停止使用的那张令牌。下面两种路径完成同一任务。

期望：单张吊销返回带 revoked_at 的记录；重复吊销返回原记录。该令牌的事件流收到 session.error，错误码为 EMBED_TOKEN_REVOKED，随后关闭；其他令牌不受影响。用户级批量撤销、封禁和解封见管理终端用户。

错误与下一步

到期后重新验证宿主登录；吊销后停止原访问；来源不允许时修正配置；用户被封禁时交由管理者处理。不要无限重签来绕过拒绝。具体错误码、HTTP 状态和恢复条件见嵌入限制与错误。

• 传入上下文
• 管理终端用户
• 打开托管对话
• 智能体 API 参考