如何为 AI Avatar 集成安全地使用 Session Token

在 SaaS 产品中接入实时 AI Avatar 时，凭证看起来很像一个小小的实现细节。对 Direct Mode 而言，它其实是一个很重要的架构边界。

Spatius 通过 Session Token，让客户端能够自行连接 Motion Server，而无需拿到你的服务端 API Key。但这并不意味着 Spatius 成了你的 Agent 层或身份系统。用户认证、权限控制、对话逻辑、ASR、LLM、TTS、轮次管理和人工交接策略，仍然由你的应用、Agent 框架或后端负责。Spatius 接收 Avatar 要说的话对应的音频，返回动作数据，再由 AvatarKit 在客户端本地渲染 Avatar。Spatius 开发者文档地图明确区分了这些职责；How It Works 概览也以架构图说明了云端动作数据与本地渲染之间的边界。

这篇文章讲的是如何把这条凭证边界设计清楚：什么该放在客户端，什么该放在后端，以及客户端需要重新连接时该如何处理。

核心要点

Session Token 只用于 Direct Mode 的客户端连接；它不能替代你的 SaaS 登录态或权限模型。
SPATIUS_API_KEY 必须只保留在后端。客户端应从你自己的、已认证的接口请求 Session Token。
每次连接都签发一个新的 Token。Spatius 文档说明，Session Token 是短期、设计为单次使用的凭证，最长有效期为 24 小时。
Token 接口应保持简单：它只负责签发 Token，不转发 Avatar 音频、不接收动作数据，也不运行你的 ASR、LLM 或 TTS 流程。
把重连当成正常产品状态来设计：过期后创建新连接需要新的 Token；已经建立的连接不会仅因为 Token 到达过期时间就受到影响。

先把系统边界讲清楚

在写接口之前，先把职责说清楚。在 Direct Mode 中，客户端运行 AvatarKit，使用 Session Token 打开 Motion Server 的 WebSocket，发送 Avatar 语音音频，接收动作数据，并在本地渲染 Avatar。小型后端服务存在的原因，是 API Key 必须保留在服务端。

关于这种职责拆分背后的通用 Web 应用模式，可参考 Auth0 对 Backend for Frontend 模式的解释、Cloudflare 对范围受限 API Token的讨论，以及 Twilio 的 API 安全基础指南。它们可帮助理解应用侧边界，但不会改变 Spatius 的运行时职责。

已完成产品认证的客户端
        │ 请求 Session Token
        ▼
你的应用后端
        │ 带着 API Key 调用 Spatius Console API
        ▼
Spatius Console API
        │ 返回 Session Token
        ▼
客户端设置 Token，再启动 AvatarKit
        │
        ▼
Motion Server → 动作数据 → 本地 AvatarKit 渲染

Token 接口刻意不处在实时 Avatar 媒体链路中。它不需要代理 Motion Server 连接、检查语音音频或接收动作数据。这正是 Direct Mode 概览描述的模型。

数据链路也应保持同样清晰。Audio 指南说明了 Avatar 运行时边缘的音频格式、时序、缓冲和打断事项；这些都不意味着 Token 签发服务需要处理音频。

这层区分不只关乎安全，也让服务更容易理解：你的应用负责判断一个已登录用户是否可以启动 Avatar 体验；这个服务只返回建立客户端连接所需的临时凭证。

如果这条边界并不符合你的架构，先暂停实现。集成路径选择指南区分了 Direct Mode、平台集成和后端自管路径，让凭证模型跟随你实际选择的运行时路径。

如果要以低风险方式先验证链路，Quickstarts 概览会先用 Session Token 和示例音频跑通 Direct Mode，再叠加团队自己的实时对话栈。

只在使用 Direct Mode 时使用 Session Token

Session Token 属于 Direct Mode。在这条路径中，由客户端自行打开 Motion Server WebSocket。

它不是每一种 Spatius 集成都要加上的通用凭证。Session Token 认证流程说明，Platform Integrations、Backend Mode 和 RTC Adapter 路径使用的是 backend-mode transport；客户端不会打开这个 Direct Mode WebSocket，也不需要 Spatius Session Token。

这是一个很重要的设计检查点。如果你的架构刻意把 Avatar 运行时流量放到后端自管管道或平台集成中，不要因为“多一层 Token 看起来更安全”就额外接入客户端 Session Token 流程。先选对集成路径，再使用该路径真正需要的凭证。

如果你正在评估多个客户端端面，请参考 SDK Capability Matrix比较各 SDK 已文档化的能力，不要假设一个平台的集成方式会原样适用于另一个平台。

关于浏览器这类公开客户端如何处理 Token，可进一步阅读 Okta 的 SPA 认证与授权说明、Curity 的 JWT 安全检查表和 Okta 的 Token 安全实践。共同原则是：浏览器只应拿到完成当前任务所需的凭证。

对产品团队来说，判断问题可以很简单：

客户端是否会通过 Direct Mode 直接连接 Motion Server？如果会，就建设 Session Token 接口；如果不会，就检查你实际选择的集成路径的认证模型。

把签发 Token 当作一次权限判定

Session Token 用于认证 Direct Mode 客户端与 Motion Server 的连接。它不应该成为你的产品绕过自身权限检查的地方。

你的接口应当在用户已经通过应用认证之后才运行。在向 Spatius 请求 Token 前，后端要做出明确的产品判断：在你自己的规则下，这个已登录用户是否有权在当前 workspace、账户或套餐中启动这个 Avatar 体验？

你的 SaaS 如何建立这个登录状态，仍然是独立的应用层问题。OWASP Authentication Cheat Sheet可作为这一层的通用参考；它不会改变 Direct Mode Session Token 的职责。

具体规则由你定义。Spatius 文档中的 Token 请求包含 App ID 和 expireAt 时间戳；它不会替代你的多租户模型、套餐权益模型或审计策略。把这一点讲清楚，可以避免一个常见错误：把连接凭证误当成完整的用户授权系统。

OWASP Authorization Cheat Sheet 可作为应用授权层面的通用实现参考，但它不会改变 Spatius Session Token 的职责：是否允许某个用户请求 Token，依然由你的应用决定。如果还在选择整体接入形态，也可以参考为 SaaS 产品自建还是采购实时数字人层？。

同一条边界也应当用于数据审查。Token 接口不应意外变成音频、提示词或应用上下文的中转站；《实时 AI Avatar 服务商应该接收哪些数据？》可以帮助团队判断哪些数据应留在各自的一侧。

一个保持边界清晰的接口可以按以下顺序执行：

用你现有的应用认证机制识别调用者。
用你自己的数据模型加载相关产品上下文，例如当前 workspace、功能权益或所选 Avatar。
判断该调用者是否可以开始 Direct Mode Avatar 会话。
若允许，从后端使用 API Key、App ID 和选定的过期时间调用 Spatius Console API。
仅把返回的 Session Token 交给这个已认证客户端。

不要仅仅因为浏览器传来了一个 user ID、套餐名称或权限标记就信任它。应从服务端已经信任的认证上下文中得出这项判断。

这种区分也与 Auth0 对 JWT Best Current Practices 草案的解读、其关于 Access Token 最小权限原则的说明、Cloudflare 对范围受限开发者凭证的讨论，以及 Curity 的 API 安全实践一致。它们只是通用安全参考，不能替代你自己的权益规则。

让 Token Server 保持小而专一

官方流程本身很精简：你的业务服务器在相应的 Console API host 上调用 POST /v1/console/session-tokens，传入 appId、expireAt，并在 X-Api-Key 请求头中携带 API Key。准确的请求字段见 Session Token API 参考，对应的 Console API 与 Motion Server 端点见 Regions 参考。

客户端侧有两个必须遵守的顺序：

从你的后端拿到 Token。
在 AvatarController.start() 打开 Motion Server 连接前，调用 AvatarSDK.setSessionToken(token)。

Web SDK 的确切行为与方法签名应以 AvatarKit Web SDK Reference为准，不应把集成指南当成完整 API 契约。

API Key 不能出现在浏览器代码、移动端构建产物、公开配置对象、示例请求或客户端错误报告中。Spatius 将它定义为服务端密钥；App ID 与 Avatar ID 是可以在客户端使用的配置值。详见 Credentials 指南。

Twilio 关于保护 Auth Token的文章，以及 Snyk 对开发流程中 API 密钥泄露的讨论，也强调了同样的实现卫生。在这个接入中，具体规则很简单：浏览器绝不能拿到 SPATIUS_API_KEY。

对你自己的接口来说，响应也应尽量朴素：只返回客户端完成当前连接建立所需的内容。不要把 API Key、无关账户信息、应用权限或内部诊断信息塞进响应。也不要把原始 Session Token 写进分析系统、客户端日志、客服截图或宽泛的请求日志中；OWASP Logging Cheat Sheet可用于制定更广泛的日志处理规则。

这个接口仍然是承载凭证响应的应用路由，应像其他此类响应一样保护传输层。OWASP Transport Layer Security Cheat Sheet可作为这一层的通用参考；它不会替代你自己的认证和权限检查。

OWASP Secrets Management Cheat Sheet 可供安全团队制定服务端密钥生命周期时参考。对于 Spatius，规则仍然很明确：API Key 留在后端，客户端只拿到启动 Direct Mode 连接所需的 Session Token。

对于敏感值的运维处理，Better Stack 关于保护日志中敏感数据的文章和 Datadog 关于降低敏感数据风险的指南都是有价值的补充。它们强调的产品决策与本接口一致：保留安全的运维元数据，而不是原始凭证。

有效期应围绕“建立连接”，而不是“用户登录”

Session Token API 要求 expireAt 晚于当前时间，且最长不超过 24 小时。选择多长的有效期，是产品和运维层面的决定；但它应该服务于建立连接的时间窗口，而不是直接沿用一个长时间的用户登录会话。

有两个生命周期细节会影响体验：

在 Token 配置的过期时间之后再尝试建立新的 Motion Server 连接，会被拒绝。
已经成功建立的连接，不会仅仅因为到达配置的过期时间而受到影响。

Spatius 也将 Session Token 描述为设计为单次使用的 Token，并建议每次客户端连接都签发新的 Token。因此客户端规则可以很明确：即将创建新的 Direct Mode 连接时——包括计划中的重连——就获取一个新的 Token。Session Token 认证流程明确区分了会被拒绝的新连接与已建立的连接。不要把之前拿到的 Token 当成可以用于下一次连接的可复用登录凭证。

这也是 Token 接口应当轻量可靠的原因。它不应在每个音频分片或每次 Avatar 动作时调用；它服务于“连接”这个动作。如果它被做成了一个塞满无关业务逻辑的复杂服务，恢复和排查都会变得更难。

Token 生命周期的通用逻辑，可以从 Okta 的五条 Token 安全建议、其对 Access Token 被盗风险的解释，以及 Curity 的 JWT 最佳实践检查表中得到不同角度的说明。安全原则看这些文章；Direct Mode 的确切生命周期仍以 Spatius Auth Flow 为准。

在上线前设计好重连和失败流程

首次跑通一次很容易。更有价值的测试是：用户重新进入 Avatar 页面、刷新页面，或在 Token 已不再适合建立连接后需要创建新连接时，产品会怎么做。

建议把这些状态在你的应用中表达清楚：

正在请求 Token： 客户端正在等待你的已认证接口响应。
正在启动 Avatar 连接： 客户端已拿到新的 Token，正在启动 AvatarKit。
已连接： Avatar 语音音频可以通过 Direct Mode 路径驱动。
可恢复的连接失败： 客户端可以根据你的产品重试策略，获取新的 Token 并尝试创建新连接。
被产品策略阻止： 用户虽然已登录，但不再满足启动体验的权益条件；用产品语言说明下一步，而不是只显示一个笼统的传输错误。

不要向用户承诺“重试一定成功”。更好的做法是让失败状态可理解，并保持清晰的重试边界：新连接使用新签发的 Token；你的产品决定是重试、展示替代方案，还是提供人工协助。

这些产品状态可以对应到 AvatarKit 已文档化的连接状态与错误回调，而不是让 UI 从一个笼统的加载状态中猜测连接结果。

把这些状态对应到 SDK 实际返回的情况，而不是统一归为一个笼统错误。Client Error Codes 指南区分了过期的 Session Token、无效 Token、超时和 WebSocket 错误；它们可能需要不同的产品响应。

对于外围服务的设计，Infisical 对动态和短期密钥的说明、Cloudflare 对服务范围 API Token的解释，以及 Twilio 的 API 安全指南都提醒团队：凭证应当范围小、可重新签发、可运维观察，但不暴露其值。

Direct Mode Token 接口上线检查表

检查问题	合理的实现方式	为什么重要
这真的是 Direct Mode 吗？	客户端将直接启动 AvatarKit 的 Motion Server 连接。	Session Token 只服务这条路径，并非所有 Spatius 集成都需要。
API Key 放在哪里？	只保存在后端使用的服务端配置中。	API Key 用于调用 Console API。
谁可以请求 Token？	已通过你的应用认证的调用者。	用户身份由你的应用负责，而不是由 Token 负责。
检查什么权限？	后端检查你定义的 workspace、功能和 Avatar 体验规则。	Session Token 不能替代多租户或套餐权限控制。
返回给客户端什么？	当前连接所需的新 Session Token。	让响应保持聚焦，减少无关数据的意外暴露。
什么时候签发？	就在创建新的 Direct Mode 连接之前。	Token 是短期、设计为单次使用的凭证。
过期后创建新连接怎么办？	客户端重新请求 Token，再启动连接。	过期后的新连接会被拒绝；已建立连接需要单独看待。
接口会转发 Avatar 运行时流量吗？	不会，只负责签发 Token。	Direct Mode 的音频、动作数据和本地渲染都在客户端路径中。
能否安全排查签发问题？	只保留运维所需的最少事件元数据，不保存原始 Token 值。	运维需要上下文，但凭证不应该变成日志数据。

在审查这张检查表时，如需进一步阅读，可对照 Infisical 的密钥生命周期建议、Cloudflare 的 API Token 范围控制以及 Snyk 提示的开发流程风险。实际实现仍需结合你自己的认证和多租户模型评估。

常见问题

Session Token 和我产品的登录会话是一回事吗？

不是。Session Token 是 Direct Mode 客户端用来认证其 Motion Server 连接的临时凭证，Session Token 认证流程对此有说明。你的 SaaS 仍应使用自己的系统认证用户，并执行 workspace、角色、套餐和功能规则。

客户端可以直接调用 Spatius Console API 吗？

不可以。Credentials 指南定义的流程是：你的业务服务器使用服务端 API Key 调用 Console API，然后把 Session Token 返回给客户端。把 API Key 发到客户端会破坏这个边界。

如果我使用 Backend Mode 或平台集成，还需要 Session Token 吗？

不需要。Session Token 认证流程只适用于 Direct Mode。集成路径选择指南说明，Backend Mode 以及平台/RTC 路径各自有自己的连接和传输认证模型。

如果用户在 Token 过期后打开一个新的 Avatar 连接，该怎么办？

让客户端再次调用你的 Token 接口，在启动这个新连接前使用新签发的 Token。具体的过期字段应以 Session Token API 参考为准；不要把旧 Token 当成可复用的登录凭证。

边界搭好一次，把产品控制权留在该在的地方

设计良好的 Session Token 接口不是第二个 Agent 后端。它是已认证 SaaS 与 Direct Mode Avatar 连接之间一个小而可审计的桥梁。你的应用继续掌控身份、权限、数据和对话行为；Spatius 专注于将 Avatar 语音音频转换成动作数据，供客户端本地渲染。

如果团队正在建立更广泛的 Token 处理规范，Auth0 对 BFF 模式的说明、Okta 对 SPA Token 处理的文章，以及 Curity 的 API 安全实践都可作为这篇集成指南之外的参考。

如果你还在判断 Direct Mode 是否适合你的产品，可以先阅读《如何把 AI Avatar 加入现有 SaaS AI Agent》和《如何在 SaaS 产品中试点 AI Avatar》。如果希望结合你的技术栈讨论集成方案，可以预约 Demo。