Overview
By default, requests that modify existing files or account settings are authenticated, but requests to upload or deliver files are not. Requests are authenticated by checking a policy string that is signed by a shared secret. Applications can be configured on an individual basis so that every request is authenticated. All security settings are configurable in the Developer Portal.
Request | Default Authentication |
---|---|
Modifies existing file | yes |
Modifies account settings | yes |
Uploads new file | no |
Delivers file | no |
Policies and Signatures
Authentication and authorization against our APIs relies on Base64URL-encoded JSON “policies” and HMAC-SHA256 “signatures”. The policy determines which actions are authorized and the signature authenticates the policy. Depending on the API, these values may be required as part of the path, query parameters, or body of a request.
The secret used for signing is automatically generated for each application. The secret should be carefully protected and never exposed client-side. A secure application stack requires backend code that generates and signs short-lived and limited-scope policies for clients. The secret can be regenerated as needed, but this will invalidate existing signatures.
Policy Structure
A policy must contain an “expiry” but can exclude all other values. A minimal policy, containing only an expiry, permits nearly all requests. The “call” value limits the types of requests allowed, and additional values limit request parameters. Getting EXIF data from image files requires explicit permission.
This policy allows any request except one to get EXIF data:
{
"expiry": 501379200
}
This policy only allows uploading and saving to custom storage:
{
"expiry": 501379200,
"call": ["pick", "store"]
}
Policy Keys
A valid policy must contain an “expiry” value set in the future, but can exclude any other values.
Key | Value | Purpose |
---|---|---|
expiry | Unix timestamp | Sets policy expiration |
call | Array of call names | Limits allowed requests, defaults to all |
handle | ID string | Limits file modifications to a single file |
container | Regex | Limits storage containers allowed for uploads |
path | Regex | Limits storage paths allowed for uploads |
url | Regex | Limits source URL’s allowed for transformations |
minSize | Size in bytes | Sets a min size for uploads |
maxSize | Size in bytes | Sets a max size for uploads |
Please notice that while using the container, path, or URL policy keys, all special characters should be escaped with a backslash in order to use them in regular expressions.
Example
The example of the url:
https://sample-domain.com/default/file_sample(1).docx
Regular expression with the properly escaped special characters:
https\:\/\/sample\-domain\.com\/default\/file_sample\(1\)\.docx
Calls
Policies without a “call” array allow every call by default except “exif”. Requests to get EXIF data require the “exif” call explicitly.
Name | Allows |
---|---|
pick | Uploading |
read | Reading |
remove | Deleting |
store | Saving to custom storage (also need “pick”) |
write | Overwriting (not new uploads) |
convert | Converting (and using the document viewer) |
exif | Getting exif metadata for image files |
stat | Getting file metadata |
runWorkflow | Running workflow jobs |
Example
The Developer Portal contains a widget to create and sign policies and each of the SDK’s contain helper functionality for the same. The below example shows how to create and use a policy for file delivery.
Create a JSON policy string:
{
"expiry": 1523595600,
"call": ["read", "convert"],
"handle": "bfTNCigRLq0QMOrsFKzb"
}
Base64URL encode the policy string:
ewogICJleHBpcnkiOiAxNTIzNTk1NjAwLAogICJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwKICAiaGFuZGxlIjogImJmVE5DaWdSTHEwUU1PcnNGS3piIgp9
Create a HMAC-SHA256 signature of the encoded policy (using ‘mysecret’ as key):
5191e4c6c304c08296eab217ee05236a5bacaab9b581b535d5922a41079b77e0
Using the policy and signature with a download URL:
https://cdn.filestackcontent.com/bfTNCigRLq0QMOrsFKzb?policy=ewogICJleHBpcnkiOiAxNTIzNTk1NjAwLAogICJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwKICAiaGFuZGxlIjogImJmVE5DaWdSTHEwUU1PcnNGS3piIgp9&signature=5191e4c6c304c08296eab217ee05236a5bacaab9b581b535d5922a41079b77e0
Using a policy and a signature when transforming your files (resize transformation URL):
https://cdn.filestackcontent.com/resize=width:300/security=policy:ewogICJleHBpcnkiOiAxNTIzNTk1NjAwLAogICJjYWxsIjogWyJyZWFkIiwgImNvbnZlcnQiXSwKICAiaGFuZGxlIjogImJmVE5DaWdSTHEwUU1PcnNGS3piIgp9,signature:5191e4c6c304c08296eab217ee05236a5bacaab9b581b535d5922a41079b77e0/bfTNCigRLq0QMOrsFKzb