Tokens API Reference - Docs

The Tokens service allows you to create, manage, and validate file tokens for your storage files. These tokens provide a way to grant temporary, controlled access to files without requiring user authentication or exposing sensitive permissions.

File tokens are particularly useful when you need to share access to private storage files with unauthenticated users or services for a limited time period. Each token is linked to a specific file and can be configured with an expiry date to ensure access is only granted for the necessary duration.

You can use tokens to generate secure URLs to view, preview, or download files. The Tokens service provides endpoints to create, list, retrieve, update, and delete tokens, giving you complete control over file access management.

For more detailed information about using file tokens in your application, refer to the File tokens documentation.

Base URL

https://<REGION>.cloud.appwrite.io/v1

Create document

Create a new Document. Before using this route, you should create a new collection resource using either a server integration API or directly from your database console.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID. You can create a new collection using the Database service server integration. Make sure to define attributes before creating documents.
- documentId string
  
  Document ID. Choose a custom ID or generate a random ID with ID.unique(). Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
- data object
  
  Document data as JSON object.
- permissions array
  
  An array of permissions strings. By default, only the current user is granted all permissions. Learn more about permissions.
Response
- 201 application/json
  
  Document
Rate limits

This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with setSession, these rate limits will still apply. Learn more about SSR rate limits.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

POST /databases/{databaseId}/collections/{collectionId}/documents

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setSession(''); // The user session to authenticate with

const databases = new sdk.Databases(client);

const result = await databases.createDocument(
    '<DATABASE_ID>', // databaseId
    '<COLLECTION_ID>', // collectionId
    '<DOCUMENT_ID>', // documentId
    {}, // data
    ["read("any")"] // permissions (optional)
);

Create documents

Create new Documents. Before using this route, you should create a new collection resource using either a server integration API or directly from your database console.

Request
- databaseId string
  required
  
  Database ID.
- collectionId string
  required
  
  Collection ID. You can create a new collection using the Database service server integration. Make sure to define attributes before creating documents.
- documents array
  
  Array of documents data as JSON objects.
Response
- 201 application/json
  
  Documents List
Rate limits

This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with setSession, these rate limits will still apply. Learn more about SSR rate limits.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 120 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	120 requests	IP + METHOD + URL + USER ID

Endpoint

POST /databases/{databaseId}/collections/{collectionId}/documents

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const databases = new sdk.Databases(client);

const result = await databases.createDocuments(
    '<DATABASE_ID>', // databaseId
    '<COLLECTION_ID>', // collectionId
    [] // documents
);

Create file token

Create a new token. A token is linked to a file. Token can be passed as a request URL search parameter.

Request
- bucketId string
  required
  
  Storage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
- fileId string
  required
  
  File unique ID.
- expire string
  
  Token expiry date
Response
- 201 application/json
  
  ResourceToken
Rate limits

This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with setSession, these rate limits will still apply. Learn more about SSR rate limits.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 60 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	60 requests	IP + METHOD + URL + USER ID

Endpoint

POST /tokens/buckets/{bucketId}/files/{fileId}

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const tokens = new sdk.Tokens(client);

const result = await tokens.createFileToken(
    '<BUCKET_ID>', // bucketId
    '<FILE_ID>', // fileId
    '' // expire (optional)
);

List tokens

List all the tokens created for a specific file or bucket. You can use the query params to filter your results.

Request
- bucketId string
  required
  
  Storage bucket unique ID. You can create a new storage bucket using the Storage service server integration.
- fileId string
  required
  
  File unique ID.
- queries string
  
  Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: expire
Response
- 200 application/json
  
  Resource Tokens List

Endpoint

GET /tokens/buckets/{bucketId}/files/{fileId}

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const tokens = new sdk.Tokens(client);

const result = await tokens.list(
    '<BUCKET_ID>', // bucketId
    '<FILE_ID>', // fileId
    [] // queries (optional)
);

Get token

Get a token by its unique ID.

Request
- tokenId string
  required
  
  Token ID.
Response
- 200 application/json
  
  ResourceToken

Endpoint

GET /tokens/{tokenId}

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const tokens = new sdk.Tokens(client);

const result = await tokens.get(
    '<TOKEN_ID>' // tokenId
);

Update token

Update a token by its unique ID. Use this endpoint to update a token's expiry date.

Request
- tokenId string
  required
  
  Token unique ID.
- expire string
  
  File token expiry date
Response
- 200 application/json
  
  ResourceToken
Rate limits

This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with setSession, these rate limits will still apply. Learn more about SSR rate limits.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 60 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	60 requests	IP + METHOD + URL + USER ID

Endpoint

PATCH /tokens/{tokenId}

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const tokens = new sdk.Tokens(client);

const result = await tokens.update(
    '<TOKEN_ID>', // tokenId
    '' // expire (optional)
);

Delete token

Delete a token by its unique ID.

Request
- tokenId string
  required
  
  Token ID.
Response
- 204 no content
Rate limits

This endpoint is not limited when using Server SDKs with API keys. If you are using SSR with setSession, these rate limits will still apply. Learn more about SSR rate limits.

The limit is applied for each unique limit key.

Time frame
Attempts
Key
1 minutes 60 requests IP + METHOD + URL + USER ID

Learn more about rate limits

Time frame	Attempts	Key
1 minutes	60 requests	IP + METHOD + URL + USER ID

Endpoint

DELETE /tokens/{tokenId}

Node.js

const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key

const tokens = new sdk.Tokens(client);

const result = await tokens.delete(
    '<TOKEN_ID>' // tokenId
);

Recommended