文件令牌 API
为 Storage 文件签发短时访问令牌(resource token):在不携带用户 Session 的场景(跨域 <img>、邮件链接、临时分享)下预览/下载文件。令牌以 token 查询参数附加到文件的 view / preview / download 端点(见 storage)。
服务与资源边界
文件令牌(File Tokens)服务用于在不暴露项目 API Key 且不要求浏览器建立登录 Session 的场景下(例如在企业智能客服会话中内联展示私有存储桶 agent_multimedia_bucket 中的工单截图,或向用户发送带时效的文档下载短链),为单个 Storage 文件({bucketId}:{fileId})签发可独立吊销的 JWT 短时访问凭证。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/tokens。资源:
resourceToken({tokenId}),挂在某个具体文件({bucketId}+{fileId})上。
认证与权限
认证与请求头约定见 通用约定。本域 scope:tokens.read(列出/读取令牌)、tokens.write(签发/更新/吊销)。令牌一旦签发,持有 secret 即可在有效期内按文件级权限读取该文件;签发与吊销务必要收紧。
端点总览
文件令牌服务提供 5 个 REST 端点,覆盖文件级令牌签发、按文件查询令牌列表、按令牌 ID 查询详情、延长/缩短过期时间及即时吊销。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
POST /tokens/buckets/{bucketId}/files/{fileId} | 为文件签发令牌 |
GET /tokens/buckets/{bucketId}/files/{fileId} | 列出该文件的令牌 |
GET /tokens/{tokenId} | 获取令牌 |
PATCH /tokens/{tokenId} | 更新有效期 |
DELETE /tokens/{tokenId} | 吊销令牌 |
端点详解
签发后的令牌以 ?token=<secret> 查询参数附加至 Storage API 的 /view、/preview 或 /download URL 尾部;服务端校验签名与 expire 有效期通过后直接放行该文件的读取操作,并在令牌的 accessedAt 字段记录最近访问时间(24 小时节流刷新)。
请求与响应
以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。认证头与示例变量约定见 通用约定。
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}。
| 字段 | 类型 | 说明 |
|---|---|---|
| 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}。
调用示例:
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} |