Docs
Contents

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

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 + pathPurpose
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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile ID
expirebodystringNoExpiration 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:

FieldTypeDescription
$idstringToken ID
$createdAtstringIssuance time (ISO 8601)
resourceIdstringProtected resource, in the format bucketId:fileId
resourceTypestringResource type, always files
expirestringExpiration time (ISO 8601)
secretstringAccess credential (in JWT form), attached to file read endpoints as ?token=
accessedAtstringThe 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:

ParameterLocationTypeRequiredDefault/enumDescription
bucketIdpathstringYesBucket ID
fileIdpathstringYesFile ID
queriesquerystring[]NoDefault []Filterable fields: expire; use limit(n)/offset(n) for pagination
totalquerybooleanNoDefault truePass false to skip counting

Output: 200, returns the resourceTokenList model: total + tokens[]. See POST /v1/tokens/buckets/{bucketId}/files/{fileId} for the resourceToken field.

FieldTypeDescription
totalintegerTotal 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:

ParameterLocationTypeRequiredDefault/enumDescription
tokenIdpathstringYesToken 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:

ParameterLocationTypeRequiredDefault/enumDescription
tokenIdpathstringYesToken ID
expirebodystringNoNew 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:

ParameterLocationTypeRequiredDefault/enumDescription
tokenIdpathstringYesToken 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

Correspondence with the Server SDK

service.methodEndpoint
Tokens.createFileTokenPOST /tokens/buckets/{bucketId}/files/{fileId}
Tokens.listGET /tokens/buckets/{bucketId}/files/{fileId}
Tokens.getGET /tokens/{tokenId}
Tokens.updatePATCH /tokens/{tokenId}
Tokens.deleteDELETE /tokens/{tokenId}