> ## Documentation Index
> Fetch the complete documentation index at: https://end-docs.shallow.ink/llms.txt
> Use this file to discover all available pages before exploring further.

# 凭证体系

> 理解 Endfield API 的双层凭证设计：接口认证 + 游戏数据凭证。

## 双层凭证架构

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 Token  | 15 分钟 | Refresh Token 刷新 |
| JWT Refresh Token | 7 天   | 重新登录             |
| Anonymous Token   | 2 小时  | 自动重新获取           |
| Framework Token   | 长期有效  | 后端自动刷新森空岛凭证      |

## 数据隔离

不同认证方式之间的数据完全隔离：

| 场景              | 数据可见性              |
| --------------- | ------------------ |
| Web 用户 A        | 只能看到自己创建的绑定        |
| API Key A 的用户 X | 只能看到 Key A 下 X 的绑定 |
| API Key B 的用户 X | **看不到** Key A 下的数据 |

<Warning>
  即使使用相同的 `user_identifier`，不同 API Key 的数据也互相不可见。这是安全隔离机制。
</Warning>

## Framework Token 与绑定

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

### 统一绑定 API

支持 Web 用户和第三方客户端两种认证方式管理绑定：

**Web 用户**（JWT 认证）：

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
curl https://api.end.shallow.ink/api/v1/bindings \
  -H "Authorization: Bearer eyJhbGciOi..."
```

**第三方客户端**（API Key + 用户标识）：

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
curl "https://api.end.shallow.ink/api/v1/bindings?user_identifier=qq_123456" \
  -H "X-API-Key: sk_xxxxxxxxxxxx"
```