认证 | Xenodia Docs

如何在服务端集成里处理 Xenodia API key、Bearer token 和 secret boundary。

Xenodia public API 使用 Bearer token。所有 runtime 调用都应从服务端发起，不要把长期 API key 暴露给浏览器。

Authorization: Bearer YOUR_LONG_TERM_KEY

cURL 模板

curl "https://api.xenodia.xyz/v1/models"

/v1/models 是 public endpoint，不需要 API key。Chat、image、video 和 task retrieval 需要认证。

curl -X POST "https://api.xenodia.xyz/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XENODIA_API_KEY" \
  -d '{"model":"gpt-6-astra","messages":[{"role":"user","content":"Hello"}]}'

Key handling

只在服务端环境变量、secret manager 或受控 agent runtime 中存放长期 key。
浏览器只应调用你自己的 backend，不应直接持有 Xenodia key。
为不同 agent 或 workflow 使用不同 key，便于撤销和审计。
轮换 key 时，同时更新 agent runtime 的 skill/env 配置。

常见状态码

Status	Meaning
`401`	缺少或无效的 API key。
`402`	余额或计费边界不足。
`403`	当前账号无权访问资源，例如 task 属于另一个 account。
`429`	Rate limit 或 quota boundary。

生产建议

把 API key、owner wallet、agent wallet 和模型访问权限当成同一个安全边界的一部分。日志里记录 request ID 和 status code，不记录 raw prompt、API key 或私钥。

API Key 列表与撤销

GET /v1/me/api-keys 的 keys 数组返回当前账户的全部密钥元数据，包含已撤销密钥。原有 data 字段继续返回最新的有效密钥元数据或 null，兼容已有客户端。查询不返回已有密钥的完整秘密值。

操作	接口	所需凭证
新增密钥	`POST /v1/me/api-keys`	Access token
撤销指定密钥	`DELETE /v1/me/api-keys/{id}`	Access token
撤销全部有效密钥	`DELETE /v1/me/api-keys`	Access token

新增只返回一次完整密钥，旧密钥继续有效。正常轮换时，先新增密钥、更新集成配置，再明确撤销旧密钥；发现泄露时应立即撤销。撤销返回 { "ok": true }，后续认证请求立即拒绝该密钥。撤销一把密钥不会影响其他密钥或浏览器会话。

登录会话、刷新与退出

Access token 与 refresh token 属于同一条可撤销的登录会话。刷新时将 refresh token 放入 POST /v1/auth/refresh 的 JSON 请求体：

{ "refresh_token": "YOUR_REFRESH_TOKEN" }

每个 refresh token 只能交换一次。客户端应串行刷新，并同时保存返回的新 access token 和 refresh token；并发交换或重放已使用令牌会返回 401。网络超时不代表服务端未处理：若重试收到 401，应重新登录，不能持续重放。

POST /v1/auth/logout 接受相同请求体，撤销这条会话及其刷新后产生的令牌，包括尚未过期的 access token。即使提交的 refresh token 已经交换过，只要其签名和有效期仍有效，仍能撤销对应会话。收到 { "ok": true } 后才能确认服务端退出成功；仅清除浏览器存储不等于撤销会话。

使用 access token 调用 POST /v1/me/sessions/revoke-all 可退出本账户全部登录会话，包含当前会话。退出登录不撤销 API Key；需要时另外调用密钥撤销接口。

会话被撤销或过期返回 401，账户被封禁或停用返回 403。可撤销会话升级后，旧版不带会话标识 sid 的 access/refresh token 需要重新登录一次；已有 API Key 保留。客户端无需解析 token 内部字段，应按 401 提示重新认证。

共用同一登录会话的标签页会协调刷新与退出。复制页面可通过短时内存消息接收已轮换的凭证，不会重复使用旧 refresh token；长期凭证不会写入 localStorage。不同登录会话互不影响。没有会话标识的旧凭证需要重新登录；页面恢复时会校验当前会话，收到服务端撤销后无需等待 access token 到期。

邀请码仅用于首次 Google 注册，失效邀请码不会阻止已有账户登录。首次注册遇到无效邀请码时，可以修改，或选择不使用邀请码继续；重试前会同时清理 URL 参数与已保存的邀请码。

认证

Header