File Tokens API
Issues short-lived access tokens (resource tokens) for Storage files: preview/download files in scenarios without a user Session (cross-origin <img>, email links, temporary sharing). The token is attached to the file's view / preview / download endpoints as a token query parameter (see storage).
Service and resource boundaries
The File Tokens service issues independently revocable JWT short-term access credentials for individual Storage files ({bucketId}:{fileId}), in scenarios where the project API Key is not exposed and no logged-in browser Session is required (for example, displaying ticket screenshots from a private storage bucket agent_multimedia_bucket inline in an enterprise intelligent customer-service conversation, or sending users a time-limited document download short link).
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/tokens.Resource:
resourceToken({tokenId}), attached to a specific file ({bucketId}+{fileId}).
Authentication and Permissions
See general conventions for authentication and request header conventions. Scopes in this domain: tokens.read (list/read tokens), tokens.write (issue/update/revoke). Once a token is issued, holding secret allows reading the file at file-level permissions within its validity period; issuance and revocation must be tightly restricted.
Endpoint overview
The File Tokens service provides 5 REST endpoints, covering file-level token issuance, querying the token list by file, querying details by token ID, extending/shortening the expiration time, and immediate revocation.
Endpoint List
| Method + path | Purpose |
|---|---|
POST /tokens/buckets/{bucketId}/files/{fileId} | Issue a token for a file |
GET /tokens/buckets/{bucketId}/files/{fileId} | List the file's tokens |
GET /tokens/{tokenId} | Get a token |
PATCH /tokens/{tokenId} | Update the expiration |
DELETE /tokens/{tokenId} | Revoke a token |
Endpoint details
After issuance, the token is appended as a ?token=<secret> query parameter to the end of the /view, /preview, or /download URL of the Storage API; once the server validates the signature and expire validity period, the file read operation is allowed directly, and the most recent access time is recorded in the token's accessedAt field (refresh throttled to 24 hours).
Requests and Responses
The following sections give inputs, outputs, copyable call examples, and response examples for each endpoint. For authentication header and example variable conventions, see general conventions.
POST /v1/tokens/buckets/{bucketId}/files/{fileId}
Issues a short-lived access token for the specified file (rate limit 60 requests/minute). Append secret to the file URL's ?token= to read the file at file-level permissions within the validity period.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID | |
expire | body | string | No | Expiration time (ISO 8601, e.g., 2020-10-15T06:38:00.000+00:00); defaults to a short default validity period |
Output: 201, returning the resourceToken model. Full field table:
| Field | Type | Description |
|---|---|---|
| $id | string | Token ID |
| $createdAt | string | Issuance time (ISO 8601) |
| resourceId | string | Protected resource, in the format bucketId:fileId |
| resourceType | string | Resource type, always files |
| expire | string | Expiration time (ISO 8601) |
| secret | string | Access credential (in JWT form), attached to file read endpoints as ?token= |
| accessedAt | string | The most recent access time using this token (not refreshed again within 24 hours) |
Call example:
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"
}'Response example:
{
"$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"
}After issuance, assemble the URL: /v1/storage/buckets/app-assets/files/66a9d9ab03c7d/view?token=<secret> (same for download / preview).
GET /v1/tokens/buckets/{bucketId}/files/{fileId}
Lists all access tokens under this file, for auditing and cleanup.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
bucketId | path | string | Yes | Bucket ID | |
fileId | path | string | Yes | File ID | |
queries | query | string[] | No | Default [] | Filterable fields: expire; use limit(n)/offset(n) for pagination |
total | query | boolean | No | Default true | Pass false to skip counting |
Output: 200, returns the resourceTokenList model: total + tokens[]. See POST /v1/tokens/buckets/{bucketId}/files/{fileId} for the resourceToken field.
| Field | Type | Description |
|---|---|---|
| total | integer | Total number of tokens |
| tokens[] | resourceToken[] | Token objects |
Call example:
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>"Response example:
{
"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}
Gets token details by ID (secret is in JWT form).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
tokenId | path | string | Yes | Token ID |
Output: 200, returning the resourceToken model; see fields in POST /v1/tokens/buckets/{bucketId}/files/{fileId}.
Call example:
curl \
"https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"$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}
Updates the token's expiration time (rate limit 60 requests/minute). This only affects future access decisions: URLs already issued with the old validity period remain usable until the new expiration takes effect (when extended) or become invalid (when shortened).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
tokenId | path | string | Yes | Token ID | |
expire | body | string | No | New expiration time (ISO 8601) |
Output: 200, returns resourceToken (focus on the expire field).
Call example:
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"
}'Response example:
{
"$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}
Revokes the token immediately (rate limit 60 requests/minute): requests holding this secret are thereafter treated as unauthorized.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
tokenId | path | string | Yes | Token ID |
Output: 204 No Content, no response body.
Call example:
curl \
-X DELETE \
"https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Errors and boundaries
Token not found:
404+token_not_found; file or bucket not found:storage_file_not_found/storage_bucket_not_found.secretis an access credential in JWT form: any call with an API Key (including creation and subsequent read endpoints) returns the full value; it is a bearer credential, and leaking it is equivalent to the file being readable within its validity period. It should only be given to parties that need to read the file, and must never appear in frontend logs or public pages.Accessing a file with an expired token is equivalent to unauthorized (determined by file permissions, typically manifesting as the 404 path, see permissions); updating
expireonly affects future access.A token is equivalent to file read permission for its validity period: only issue tokens for necessary files, use the shortest possible validity, and revoke after use; do not distribute the issuance API Key to the browser—have a function/backend issue the short link and return it to the frontend.
The issuance endpoint is rate-limited to 60 requests/minute; batch distribution scenarios should reuse the same token rather than issuing per request.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
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} |