API Token

为第三方工具创建与管理长期 API 令牌。

API Token 是为 PicGo、ShareX 等第三方客户端设计的长期令牌，与用户登录返回的 Access Token 相比：

特性	Access Token	API Token
有效期	2 小时	默认永久 / 自定义
刷新	通过 Refresh Token	不需要
存储	仅内存	数据库（仅 SHA256 哈希）
使用场景	Web 浏览器、短时会话	脚本、图床客户端

安全模型

创建 Token 时会生成随机字符串并立即 SHA256 入库，明文仅返回一次。
客户端请求时传入明文，服务端 SHA256 后与数据库比对。
一旦丢失无法找回，只能删除后重新生成。

创建 Token

Endpoint

POST · /api/v1/tokens · 需认证

请求

{
  "name": "PicGo MacBook",
  "expires_in": 365
}

字段	类型	说明
`name`	string	必填，用于自己识别，最长 100 字符
`expires_in`	int \| null	有效期天数，`null` 或省略表示永不过期

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "token-uuid",
    "name": "PicGo MacBook",
    "token": "kite_pat_a1b2c3d4e5f6...",
    "expires_at": "2027-04-17T10:00:00Z",
    "created_at": "2026-04-17T10:00:00Z"
  }
}

注意

token 字段仅在创建时返回一次。请立刻复制保存；关闭此响应后无法再次查看明文。

Token 列表

Endpoint

GET · /api/v1/tokens · 需认证

返回当前用户的所有 Token，不包含明文。

响应

{
  "code": 0,
  "data": [
    {
      "id": "token-uuid",
      "name": "PicGo MacBook",
      "last_used": "2026-04-17T09:30:00Z",
      "expires_at": "2027-04-17T10:00:00Z",
      "created_at": "2026-04-17T10:00:00Z"
    }
  ]
}

字段	说明
`last_used`	最近一次成功认证时间；`null` 表示未使用
`expires_at`	过期时间，`null` 表示永不过期

删除 Token

Endpoint

DELETE · /api/v1/tokens/:id · 需认证

删除后该 Token 立即失效。无法通过删除-创建恢复同一个 Token 值 —— 每次创建都是全新的随机串。

使用 Token

在任意业务端点的请求头中使用：

Authorization: Bearer kite_pat_a1b2c3d4e5f6...

对于兼容兰空协议的客户端（如 PicGo），请注意 token 字段必须包含 Bearer 前缀：

Token: Bearer kite_pat_a1b2c3d4e5f6...

详见第三方客户端。

Token 能做什么？

API Token 在认证层面与 Access Token 等价，可访问当前用户可见的所有业务接口：

✅ 上传、列表、删除当前用户的文件
✅ 操作当前用户的相册
✅ 查看个人资料与统计
❌ 访问管理员专用接口（即便用户是管理员，API Token 也仅拥有普通用户权限）

说明

这是有意的设计 —— 避免 API Token 意外暴露后带来管理权限失守。管理员在后台操作请使用浏览器登录。

轮换建议

为每个客户端单独创建 Token（如 PicGo-MBP、ShareX-Desktop），便于丢失单个设备时只撤销对应 Token。
对关键环境（共享电脑、CI）设置有限的 expires_in，到期自动失效。
定期查看 last_used，清理不再使用的 Token。

下一步

第三方客户端 · PicGo / ShareX 配置示例
管理员 API