XAOCEN ACCOUNT / DEVELOPER ACCESS

一套账号，
连接每一个产品。

这里是 XAOCEN Account 的公开接入索引，面向 XAOCEN STUDIO 自有产品和经过确认的合作项目。统一账号、设备、权益、离线授权和遥测，各自按最小需要接入。

当前开放范围：Account 项目 · v1完整字段和错误码以项目内的版本化协议文件为准；本页不展示任何服务端秘密。

项目与接口范围

XAOCEN Account 是统一账号项目，负责当前的账号、设备、会员权益与授权 API。其他产品通过这些接口使用公共账号能力，并不因此对外提供自己的业务 API。

XAOCEN Reader 与 XAOCEN PLANET（晓枨星球）的业务 API 作为后续规划预留，目前尚未开放，也没有可用接口地址或发布日期。接入文档公开不代表任意第三方已经获得生产访问权限。

SERVICE ENTRANCE

先选对环境。

测试和生产完全隔离。正式客户端、正式产品页面和生产数据不得引用测试地址。

生产环境

XAOCEN Account

https://auth.xaocen.studio/v1

原生客户端使用的正式入口。网页账号页面优先使用官网同源的 /account-api/v1。

测试环境

联调专用

https://telemetry-test.xaocen.studio/v1

仅供测试站和测试客户端使用，账号、权益、遥测和数据库与生产环境分离。

测试环境地址不能写入正式客户端。生产发布前需要重新构建，并核对运行配置未指向 web-test.xaocen.studio、telemetry-test.xaocen.studio 或测试凭据。

PROTOCOL MAP

按需要接入，不复制多余能力。

产品可以只接入账号，也可以继续接入设备、权益、离线授权或匿名遥测。

账号与会话

先建立统一身份

网页使用 HttpOnly 刷新会话；原生客户端使用短时访问令牌和操作系统凭据存储中的刷新令牌。

  • POST /v1/auth/register
  • POST /v1/auth/login
  • POST /v1/auth/refresh
  • POST /v1/auth/logout
设备与权益

再判断产品能力

每个产品使用固定 productId 和 platform 查询自己的权益，不把登录成功误认为拥有全部产品权限。

  • POST /v1/auth/device/start
  • POST /v1/auth/device/status
  • GET /v1/account/entitlements
  • POST /v1/account/device/approve
离线与恢复

为无网场景保留出口

离线设备生成密钥，联网设备申请签发；客户端固定内置公钥并在本地验证签名、产品、平台、设备和时间策略。

  • POST /v1/account/offline/request
  • POST /v1/account/offline-license
  • POST /v1/auth/offline/check
  • POST /v1/auth/offline/refresh

REUSE THE FLOW

跨产品接入流程。

各项目须确认产品标识、接入权限与自身业务边界，再按协议实现和验证。

01

确定产品身份

为产品固定唯一 productId 和平台值；同一产品的授权、权益、反馈和遥测都复用这组标识。

02

实现最小会话层

完成登录、刷新、退出和 401 重新授权；访问令牌只放内存，刷新令牌放系统安全存储。

03

接入设备与权益

原生客户端用设备授权换取会话，登录成功或重启恢复后查询自身权益，再由产品决定基础功能与会员功能边界。

04

按需加入离线授权

只有确实需要断网运行的产品才接入设备公钥、compactLicense、本地签名验证和联网复核。

REQUEST BASELINE

请求从这里开始。

所有请求使用 HTTPS 和 JSON；需要登录的接口使用 Bearer 访问令牌。客户端必须按 code 处理错误，不依赖中文提示文字。

POST /v1/auth/device/start
Content-Type: application/json

{
  "productId": "your-product-id",
  "platform": "windows-x64",
  "deviceName": "可选设备名称"
}

RESPONSE RULES

只信协议，不猜状态。

200 / 201接受全部成功的 2xx 响应，不把成功状态写死为单一数字。
401会话失效或令牌无效；原生客户端清理本地令牌并重新授权。
403 / 409分别处理权限或设备不匹配、并发重复或设备上限。
429 / 5xx按退避策略重试，并记录 requestId；不要记录令牌和授权内容。

SECURITY BOUNDARY

安全边界要先写进项目。

不把密码、访问令牌、刷新令牌、OAuth Secret、数据库凭据或离线签名私钥写入客户端、日志、遥测和公开文档。离线授权只信任发行版内置公钥，公钥轮换必须先发布客户端再切换签发端。

申请接入沟通 ↗

DOCUMENTATION

项目接入资料

完整协议、离线授权手册、权益策略、遥测协议和 C# 适配说明均在 XAOCEN STUDIO 项目文档中维护。项目接入前应核对协议及接入权限，并按自身产品补充权益和隐私说明。

隐私政策 ↗使用协议 ↗提交反馈 ↗