TokenProto 开放平台（账单）鉴权说明

1. 服务与路径前缀

项	说明
完整调用示例	`https://{console-host}/api/account/order/list`
鉴权范围	开放平台账单类接口统一走开放平台凭证或控制台 JWT 鉴权
适用接口	`/api/account/bill/stats/`、`/api/account/order/`

开放平台接口与 Gateway 模型调用接口（/v1/*，API Key 鉴权）完全独立，凭证不互通。

2. 认证方式（二选一）

开放平台支持两种鉴权方式，二者取其一即可，均解析为同一 sys_user，权限判定一致。

方式 A：开放平台凭证（`x-user-code` + `x-user-token`）

两个请求头 必须同时携带，缺一不可。

在控制台登录后，于 账单明细 或 账单统计 页「开放平台凭证」卡片中生成。

Code 与 Token 各 32 位（数字 + 大小写字母）。

方式 B：控制台 JWT

与网页登录态相同，适合控制台前端内部调用或调试。

以 Bearer 开头，后跟 JWT 明文。

解析优先级

若同时携带 凭证头与 JWT，优先使用凭证头（x-user-code + x-user-token）。

3. 凭证与平台用户

凭证（x-user-code / x-user-token）解析到生成它的 控制台用户（sys_user）。

接口仅返回 该用户自己的账单数据，凭证 不提升权限。

若该用户角色未分配账单菜单权限（account:bill:order:query / account:bill:stats:query），即使凭证有效也会收到 403。

重新生成凭证后，旧凭证 立即失效。

4. 未授权与禁止访问响应

401（凭证无效或过期）

{
  "code": 401,
  "msg": "凭证无效或已过期"
}

HTTP 状态码	场景
401	未携带 `x-user-code` / `x-user-token` 或 JWT
401	凭证已被重新生成（旧凭证失效）
401	JWT 过期

403（角色无权限）

{
  "code": 403,
  "msg": "当前用户无该接口权限"
}

HTTP 状态码	场景
403	用户角色未分配对应账单菜单权限（`account:bill:*`）

5. 凭证生成（仅控制台登录态）

凭证 不对接方开放生成接口，请在控制台生成：

登录用户控制台

进入 账单明细 或 账单统计 页面

展开顶部 开放平台凭证 卡片

点击 生成凭证 或 重新生成

后端接口（仅 JWT 可调用，不对接方开放）：

方法	路径	说明
GET	`/api/account/token`	查询当前用户凭证列表
POST	`/api/account/token/generate`	首次生成或重新生成

6. curl 示例

凭证方式

JWT 方式

7. 安全建议

凭证等同于账号密码片段，勿提交到公开仓库或前端代码

泄露后立即在控制台 重新生成，旧凭证即时失效

凭证仅用于账单只读查询，不具备 模型调用能力

8. 与 Gateway 鉴权的区别

项	开放平台凭证	Gateway API Key
用途	查询账单（console 后台）	调用 AI 模型 `/v1/*`
请求头	`x-user-code` + `x-user-token`	`Authorization: Bearer` 或 `x-api-key`
管理入口	控制台账单页「开放平台凭证」	模型 → API Key
权限	角色菜单 `account:bill:*`	模型调用配额/分组
数据范围	仅当前用户自己的账单	按租户/分组配额

鉴权方式说明

TokenProto 开放平台（账单）鉴权说明#

1. 服务与路径前缀#

2. 认证方式（二选一）#

方式 A：开放平台凭证（x-user-code + x-user-token）#

方式 B：控制台 JWT#

解析优先级#

3. 凭证与平台用户#

4. 未授权与禁止访问响应#

401（凭证无效或过期）#

403（角色无权限）#

5. 凭证生成（仅控制台登录态）#

6. curl 示例#

凭证方式#

JWT 方式#

7. 安全建议#

8. 与 Gateway 鉴权的区别#