Getting Started

Filestack Architecture

File Upload

File Export (Save To)

Responsive Images

Image Transformations

Document Transformations

Video Transcoding

Audio Transcoding





Filestack Viewer


Supported Cloud Drives

Filestack Recipes

Filestack Integrations

Filestack SDKs

Register for an API key

Security - Creating Filestack File Policies


In order to secure urls, you will need two things. First, a policy that says what the user is allowed to do. Since the user might modify their policy and give themselves additional privileges, you will need to create a signature of the policy, that only you can generate. This way, no one will be able to tamper with the assigned policy.

Hash Message Authentication Code (HMAC)

HMAC generates a signature from a message. Only those who have the secret can generate the correct signature for the message. Those who have the message and the signature cannot figure out what the secret is nor can they modify the message so that the signature is still valid. Filestack and you have a shared secret in your developer portal (in the security section). By signing your policy with this secret, Filestack can verify your identify. There are no known security flaws or attacks on HMAC.

This secret is how we can verify you are who you say you are. Do not share this secret. Do not store this on the client.

Example code for Python
import base64
import json
import time

handle = 'KW9EJhYtS6y48Whm2S6D'
expiry = str(int(time.time() + 60*60))
json_policy = '{"handle":"%s","expiry":%s}' % (handle, expiry)
# example json_policy: '{"handle":"KW9EJhYtS6y48Whm2S6D","expiry":1508141504}'

policy = base64.urlsafe_b64encode(json_policy)
# example policy: eyJoYW5kbGUiOiJLVzlFSmhZdFM2eTQ4V2htMlM2RCIsImV4cGlyeSI6MTUwODE0MTUwNH0=
print policy

Generating a policy

Policies define what the user can and cannot do. Since these are time based and not single use, you can do interesting things with them, like allow all users to read but prevent writes. Since these signatures are meant to be reused, you should be careful with them. Setting short expirations will reduce the likelyhood of replay attacks.

Filestack file policies are URL safe Base64 JSON parseable strings. To generate a policy, create a json object with the appropriate key value pairs. Then base64 encode it. URL safe is done by replacing '+' with '-' and '/' with '_'.

Base64 also include trailing '=' as padding. You will need to leave these in.

Note that the ordering doesn't matter on the underlying JSON object. Since you will stringify it, we will verify the signature against the string you've provided. You may find that your ordering might be slightly different and thus vary from the example below.


Required inputs

The expiration date of this policy after which it will no longer be valid. The type should be an integer and it is expressed in seconds since the Epoch (1970), a standard computer science concept. All major languages have a way of calculating this easily.

# For 1 hour expirations
# Javascript:   Math.floor(new Date()
        .getTime() / 1000 + 60*60)
# Python:       int(time.time() + 60*60)
Expiry:         1350465080
Optional inputs

The calls that you allow this policy to make. This can be one of the following:

  • pick - (allows user to upload file)
  • read - (allows file to be viewed/accessed)
  • stat - (allows metadata about file to be retrieved)
  • write - (allows use of the write function)
  • writeUrl - (allows use of he writeUrl function)
  • store - (allows files to be written to custom storage)
  • convert - (allows transformation (crop, resize, rotate) of files)
  • remove - (allows removal of Filestack files)
  • exif - (allows exif metadata to be accessed)

It can take one of the strings above, or you can also pass in multiple calls by making it an array of strings.

handle The unique file handle that you would like to access. A Filestack file URL like has a handle of KW9EJhYtS6y48Whm2S6D. This is for all calls that act on a specific handle. Pick is not affected by this input as no handle exists yet for the file.
url It is possible to create a subset of external URL domains that are allowed to be image/document sources for transformations. The filter is a regular expression that must match the input URL. The following is an example of a policy that restricts conversion requests to urls from wikimedia. {"expiry":1577836800,"call":["convert"],"url":"https://upload\\.wikimedia\\.org/wikipedia/.*"}
maxSize The maximum size that can be stored into your s3. This only applies to the store command. Default to no limit.
minSize The minimum size that can be stored into your s3. This only applies to the store command. Together with maxSize, this forms a range. The value of minSize should be smaller then maxSize. Default to 0.
path For policies that store files, a perl-like regular expression that must match the path that the files will be stored under. Defaults to allowing any path ('.*').
container For policies that store files, a perl-like regular expression that must match the container that the files will be stored under. Defaults to allowing any container ('.*').