API 令牌 1.0 预览版
API 令牌给手机 App、脚本这类客户端用：带上令牌就能访问 pt-tools 的 App 接口（/api/app/v1/）、登录 qB 兼容入口，或者让 AI 助手经 MCP 调用 pt-tools，客户端里不用保存网页的登录密码。令牌访问不了网页的其他功能，那些仍然要登录。
入口在「系统 → API 令牌」。
新建令牌
- 点「新建」，填名字（例如「我的手机」），选权限与有效期。
- 新建以后弹出的窗口里是令牌本身，以
ptt_开头。它只显示这一次：复制下来填进客户端，关掉窗口以后就看不到了。丢了就撤销再建一个。
| 权限 | 能做什么 |
|---|---|
| 读取 | 概览、站点、下载器里的种子、RSS 推送记录、搜索、刷流任务、整理历史、订阅与探索 |
| 操作 | 暂停、继续、删除种子，推送种子，签到，建订阅、暂停或恢复订阅、立即搜索、删除订阅 |
| qB 兼容 | 登录 qB 兼容入口：MoviePilot、IYUU 这类只认 qBittorrent 的工具用，和上面两个互不相干 |
| MCP 读取 | AI 助手经 MCP 调用只读工具：查看种子、下载器、站点数据与订阅，搜索种子 |
| MCP 操作 | AI 助手经 MCP 暂停、继续、删除、推送种子，添加订阅；每次都要 AI 先向你确认 |
只选「操作」的令牌读不了数据，App 这类客户端通常两个都要；给 qB 兼容入口用的令牌只选「qB 兼容」；给 AI 助手用的令牌选「MCP 读取」，要让它改动下载器再加「MCP 操作」。有效期可选 30 天、90 天、1 年或不过期，过期以后令牌自动失效。最多建 50 个令牌。
用令牌访问
客户端在每个请求里带上 Authorization: Bearer <令牌>。令牌只认这个请求头，不认地址里的参数。
bash
curl -H "Authorization: Bearer ptt_1_xxxxxxxx" https://pt-tools.example.com/api/app/v1/meta接口清单见 App API。
撤销与使用情况
- 列表写明每个令牌的权限、最近一次使用的时间与过期时间。最近一次使用每 5 分钟最多更新一次。
- 「撤销」立即生效，用这个令牌的客户端马上就连不上了。
- 令牌调用「操作」接口都记在「ChatOps → 操作审计」里，因为权限不够被拒的也记：通道是「API 令牌」，触发用户是令牌编号。经 MCP 调用会改动下载器或订阅的工具也记在这里，通道是「MCP」，见 MCP。
安全
- pt-tools 只保存令牌的 SHA-256 摘要，不保存令牌本身，数据库被别人拿到也还原不出令牌。
- 令牌和密码一样要保管好。在公网上访问时请用 HTTPS（例如放在反向代理之后），否则令牌会以明文经过网络。
- 网页的设置、站点 Cookie、下载器与通知通道这些接口只认网页登录，令牌访问不了，也新建不了别的令牌。