个人访问令牌（PAT）¶
个人访问令牌（Personal Access Token，PAT）供 SDK 与自动化脚本使用，以令牌所属用户的身份访问 Inklet API，无需交互式登录。PAT 不支持独立 Scope——其权限与用户当前权限完全同步。
Base URL
本页所有接口的 Base URL 为 https://dev.iminklet.com。
概述¶
PAT 的使用方式与普通访问令牌完全相同，在 HTTP 请求头中以 Bearer 方式提供：
与普通访问令牌的区别：
- PAT 不参与
X-Renewed-Token滑动续签机制。 - PAT 不能调用 PAT 管理接口（创建、列表、撤销）；管理接口必须使用常规用户 Access Token。
- PAT 的权限随用户当前权限实时同步，不引入 Scope、Project、Workspace 或 Service Account 隔离。
安全建议¶
安全注意事项
- 不要将 PAT 提交到 Git 仓库、写入日志或 Trace、拼接到 URL 或 query string 中。
- 使用 Secret Manager 或环境变量存储 PAT。
- 设置合理的过期时间，定期轮换；一旦泄露立即撤销。
PAT 模型¶
{
"id": "01912345-6789-7abc-def0-123456789abc",
"name": "home automation",
"prefix": "il_pat_abcdef",
"lastFour": "wxyz",
"createdAt": "2026-01-15T10:30:00Z",
"lastUsedAt": "2026-07-01T08:00:00Z",
"expiresAt": "2027-01-01T00:00:00Z",
"revokedAt": null
}
| 字段 | 类型 | 描述 |
|---|---|---|
id |
UUID | PAT 的数据库主键 |
name |
string | 用户为该令牌设置的名称（最多 100 个字符） |
prefix |
string | 令牌前缀（il_pat_ 加后续 6 位），用于辨识 |
lastFour |
string | 令牌末四位，用于辨识 |
createdAt |
timestamp | 创建时间 |
lastUsedAt |
timestamp 或 null | 最后使用时间（最多每 5 分钟更新一次，最终一致） |
expiresAt |
timestamp 或 null | 过期时间；null 表示永不过期 |
revokedAt |
timestamp 或 null | 撤销时间；null 表示未撤销 |
安全存储
服务端仅存储令牌的 SHA-256 摘要，明文令牌只在创建响应中返回一次。遗失后只能撤销并重建。
接口列表¶
POST /api/personal-access-tokens¶
需要常规用户 Access Token
创建新的个人访问令牌。
请求头：
请求体：
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
name |
string | 是 | 令牌名称，1–100 个字符 |
expiresAt |
string（RFC 3339） | 否 | 过期时间，必须在当前时间之后；省略则永不过期 |
响应： 201 Created
{
"id": "01912345-6789-7abc-def0-123456789abc",
"name": "home automation",
"prefix": "il_pat_abcdef",
"lastFour": "wxyz",
"createdAt": "2026-01-15T10:30:00Z",
"lastUsedAt": null,
"expiresAt": "2027-01-01T00:00:00Z",
"revokedAt": null,
"token": "il_pat_abcdefghijklmnopqrstuvwxyz0123456789ab"
}
令牌只显示一次
响应中的 token 字段是完整的明文令牌，仅在此次创建响应中返回。请立即安全保存。后续列表接口不再返回明文令牌；一旦遗失，只能撤销后重建。
错误：
| 状态码 | 原因 |
|---|---|
400 |
name 为空或超过 100 个字符，或 expiresAt 不在未来时间 |
401 |
访问令牌缺失或无效 |
403 |
调用方本身是 PAT（PAT 不能管理 PAT） |
GET /api/personal-access-tokens¶
需要常规用户 Access Token
列出当前用户的所有个人访问令牌。
请求头：
响应： 200 OK
[
{
"id": "01912345-6789-7abc-def0-123456789abc",
"name": "home automation",
"prefix": "il_pat_abcdef",
"lastFour": "wxyz",
"createdAt": "2026-01-15T10:30:00Z",
"lastUsedAt": "2026-07-01T08:00:00Z",
"expiresAt": "2027-01-01T00:00:00Z",
"revokedAt": null
},
{
"id": "01912345-6789-7abc-def0-000000000002",
"name": "ci pipeline",
"prefix": "il_pat_ghijkl",
"lastFour": "1234",
"createdAt": "2026-03-10T09:00:00Z",
"lastUsedAt": null,
"expiresAt": null,
"revokedAt": "2026-06-01T12:00:00Z"
}
]
列表响应不包含 token 字段——仅展示名称、前缀、末四位、创建、最后使用、过期与撤销状态。
错误：
| 状态码 | 原因 |
|---|---|
401 |
访问令牌缺失或无效 |
403 |
调用方本身是 PAT（PAT 不能管理 PAT） |
DELETE /api/personal-access-tokens/{id}¶
需要常规用户 Access Token
按 ID 撤销指定个人访问令牌。撤销立即生效，后续使用该令牌的请求将返回 401。接口对同一令牌的重复撤销请求是幂等的。
路径参数：
| 参数 | 描述 |
|---|---|
id |
要撤销的 PAT UUID |
请求头：
响应： 204 No Content
撤销成功，响应无正文。
错误：
| 状态码 | 原因 |
|---|---|
400 |
id 不是有效 UUID |
401 |
访问令牌缺失或无效 |
403 |
调用方本身是 PAT（PAT 不能管理 PAT） |
错误行为¶
以下情况均返回 401 Unauthorized，不暴露具体原因：
- PAT 已过期
- PAT 已被撤销
- 令牌格式无效或哈希不匹配
- 所属用户已被删除或停用
PAT 不参与 X-Renewed-Token 响应头，该机制仅适用于 JWT 访问令牌。
使用示例¶
创建 PAT（使用常规 Access Token）¶
curl -X POST https://dev.iminklet.com/api/personal-access-tokens \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"home automation","expiresAt":"2027-01-01T00:00:00Z"}'