文件令牌 API
为 Storage 文件签发短时访问令牌(resource token):在不携带用户 Session 的场景(跨域 <img>、邮件链接、临时分享)下预览/下载文件。令牌以 token 查询参数附加到文件的 view / preview / download 端点(见 storage)。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/tokens。 - 资源:
resourceToken({tokenId}),挂在某个具体文件({bucketId}+{fileId})上。
认证与权限
认证与请求头约定见 通用约定。本域 scope:tokens.read(列出/读取令牌)、tokens.write(签发/更新/吊销)。令牌一旦签发,持有 secret 即可在有效期内按文件级权限读取该文件;签发与吊销务必要收紧。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
POST /tokens/buckets/{bucketId}/files/{fileId} | 为文件签发令牌 |
GET /tokens/buckets/{bucketId}/files/{fileId} | 列出该文件的令牌 |
GET /tokens/{tokenId} | 获取令牌 |
PATCH /tokens/{tokenId} | 更新有效期 |
DELETE /tokens/{tokenId} | 吊销令牌 |
请求与响应
以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。认证头与示例占位符约定见 通用约定。
POST /v1/tokens/buckets/{bucketId}/files/{fileId}
为指定文件签发短时访问令牌(限流 60 次/分钟)。secret 拼到文件 URL 的 ?token= 上即可在该有效期内按文件级权限读取文件。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID | |
expire | body | string | 否 | 过期时间(ISO 8601,如 2020-10-15T06:38:00.000+00:00);缺省为短默认时效 |
输出:201,返回 resourceToken 模型。完整字段表:
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 令牌 ID |
| $createdAt | string | 签发时间(ISO 8601) |
| resourceId | string | 受保护资源,格式 bucketId:fileId |
| resourceType | string | 资源类型,恒为 files |
| expire | string | 过期时间(ISO 8601) |
| secret | string | 访问凭证(JWT 形态),以 ?token= 附加到文件读取端点 |
| accessedAt | string | 最近一次用该令牌访问的时间(24 小时内不重复刷新) |
调用示例:
curl \
-X POST \
"https://<your-endpoint>/v1/tokens/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"expire": "2020-10-15T06:38:00.000+00:00"
}'响应示例:
{
"$id": "bb8ea5c16897e",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"resourceId": "app-assets:66a9d9ab03c7d",
"resourceType": "files",
"expire": "2020-10-15T06:38:00.000+00:00",
"secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"accessedAt": "2020-10-15T06:38:00.000+00:00"
}签发后即可拼 URL:/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/view?token=<secret>(download / preview 同理)。
GET /v1/tokens/buckets/{bucketId}/files/{fileId}
列出该文件名下的全部访问令牌,用于审计与清理。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID | |
queries | query | string[] | 否 | 默认 [] | 可过滤字段:expire;分页用 limit(n)/offset(n) |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 resourceTokenList 模型:total + tokens[]。resourceToken 字段见 [POST /v1/tokens/buckets/{bucketId}/files/{fileId}](#post-v1tokensbucketsbucketidfilesfileid)。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 令牌总数 |
| tokens[] | resourceToken[] | 令牌对象 |
调用示例:
curl \
'https://<your-endpoint>/v1/tokens/buckets/app-assets/files/66a9d9ab03c7d?queries[]=limit(25)&total=false' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"tokens": [
{
"$id": "bb8ea5c16897e",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"resourceId": "app-assets:66a9d9ab03c7d",
"resourceType": "files",
"expire": "2020-10-15T06:38:00.000+00:00",
"secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"accessedAt": "2020-10-15T06:38:00.000+00:00"
}
]
}GET /v1/tokens/{tokenId}
按 ID 获取令牌详情(secret 为 JWT 形态)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
tokenId | path | string | 是 | 令牌 ID |
输出:200,返回 resourceToken 模型,字段见 [POST /v1/tokens/buckets/{bucketId}/files/{fileId}](#post-v1tokensbucketsbucketidfilesfileid)。
调用示例:
curl \
"https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "bb8ea5c16897e",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"resourceId": "app-assets:66a9d9ab03c7d",
"resourceType": "files",
"expire": "2020-10-15T06:38:00.000+00:00",
"secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"accessedAt": "2020-10-15T06:38:00.000+00:00"
}PATCH /v1/tokens/{tokenId}
更新令牌过期时间(限流 60 次/分钟)。只影响未来的访问判定,已用旧时效发出的 URL 在新过期时间生效前依然可用(延长的情形)或已失效(缩短的情形)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
tokenId | path | string | 是 | 令牌 ID | |
expire | body | string | 否 | 新过期时间(ISO 8601) |
输出:200,返回 resourceToken(关注 expire 字段)。
调用示例:
curl \
-X PATCH \
"https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"expire": "2020-10-15T06:38:00.000+00:00"
}'响应示例:
{
"$id": "bb8ea5c16897e",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"resourceId": "app-assets:66a9d9ab03c7d",
"resourceType": "files",
"expire": "2020-10-15T06:38:00.000+00:00",
"secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"accessedAt": "2020-10-15T06:38:00.000+00:00"
}DELETE /v1/tokens/{tokenId}
立即吊销令牌(限流 60 次/分钟):持有该 secret 的请求此后等效未授权。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
tokenId | path | string | 是 | 令牌 ID |
输出:204 No Content,无响应体。
调用示例:
curl \
-X DELETE \
"https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"错误与边界
- 令牌不存在:
404+token_not_found;文件或桶不存在:storage_file_not_found/storage_bucket_not_found。 secret为 JWT 形态的访问凭证:凡以 API Key 调用(含创建与后续读取端点)都会返回完整值;它是 bearer 凭证,泄露即等同在有效期内可读该文件,只应下发给需要读取的一方,切勿出现在前端日志或公开页面。- 过期令牌访问文件等效未授权(按文件权限判定,典型表现为 404 路径,见 permissions);更新
expire只影响未来访问。 - 令牌等同于有效期内的文件读权:只对必要文件签发、尽量短时效、用后吊销;不要把签发用 API Key 下发到浏览器——由函数/后端签发短链再返回前端。
- 签发端点限流 60 次/分钟;批量分发场景应复用同一令牌而非逐请求签发。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Tokens.createFileToken | POST /tokens/buckets/{bucketId}/files/{fileId} |
Tokens.list | GET /tokens/buckets/{bucketId}/files/{fileId} |
Tokens.get | GET /tokens/{tokenId} |
Tokens.update | PATCH /tokens/{tokenId} |
Tokens.delete | DELETE /tokens/{tokenId} |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/tokens域 5 个端点、resourceToken/resourceTokenList模型)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0Tokensservice。 - 语义深度参考:
skills/ob-agentbase/references/file-tokens.md。