Skip to main content

​
双层凭证架构

Endfield API 采用接口认证和游戏数据凭证分离的设计： 
API 请求
├─ 接口认证层（三选一，证明调用权限）
│   ├─ API Key        → X-API-Key 头
│   ├─ JWT            → Authorization: Bearer 头
│   └─ Anonymous Token → X-Anonymous-Token 头
│
└─ 游戏数据层（可选，查询游戏数据时必须）
    └─ Framework Token → X-Framework-Token 头

​
为什么分离？

  • 接口认证解决的是”谁在调用”的问题 — 用于配额计量和速率限制
  • 游戏数据凭证解决的是”查谁的数据”的问题 — 关联到具体的森空岛账号
一个 API Key 可以管理多个 Framework Token（多个游戏账号），实现多用户数据查询。

​
凭证生命周期

凭证有效期刷新方式
API Key长期有效手动吊销/重建
JWT Access Token15 分钟Refresh Token 刷新
JWT Refresh Token7 天重新登录
Anonymous Token2 小时自动重新获取
Framework Token长期有效后端自动刷新森空岛凭证

​
数据隔离

不同认证方式之间的数据完全隔离：
场景数据可见性
Web 用户 A只能看到自己创建的绑定
API Key A 的用户 X只能看到 Key A 下 X 的绑定
API Key B 的用户 X看不到 Key A 下的数据
即使使用相同的 user_identifier，不同 API Key 的数据也互相不可见。这是安全隔离机制。

​
Framework Token 与绑定

登录流程（扫码/手机/Cred）
    ↓
获取 Framework Token → 写入凭证库（含森空岛 cred/token）
    ↓
用户绑定（可选）→ 写入绑定库（关联 Framework Token）
    ↓
API 查询 → 用 Framework Token 从凭证库取凭证 → 调用森空岛 API

​
统一绑定 API

支持 Web 用户和第三方客户端两种认证方式管理绑定： Web 用户（JWT 认证）： 
curl https://api.end.shallow.ink/api/v1/bindings \
  -H "Authorization: Bearer eyJhbGciOi..."
第三方客户端（API Key + 用户标识）： 
curl "https://api.end.shallow.ink/api/v1/bindings?user_identifier=qq_123456" \
  -H "X-API-Key: sk_xxxxxxxxxxxx"