Security + Permissions

Signed vs Unsigned requests

A signed request is one which came from a trusted source. Requests can be signed either with your private key (for example if the request came from a secure server) or with an authentication token.

Unsigned requests come from anonymous sources, such as client-side code being run by one of your users. Only your public key is required to generate an unsigned request.

Our libraries authorize requests automatically, but you can find instructions on how to sign requests manually in the API documentation.

App and File Permissions

Each file has a read permission. On an app level, you can choose the read permission newly uploaded files start with, and whether reading anything in the app needs a signed URL.

Read decides who can request and download a file, through its file, data and image URLs (transforms and labels included):

• Anyone with the link (public): any request may read it. This is the default.
• Signed URLs only (authenticated): only a URL signed with your private key, or your server using the private key, may read it. Unsigned requests are refused with 401, even when the app itself allows unsigned links. See signed URLs.

Two app settings control reading, and they are not the same thing:

• Read access (require signed URLs): every file, image and video in the app, including the ones already uploaded, needs a signed URL, whatever each file is set to. This is the way to make a whole app private, and the only way to require signatures for videos.
• Default read permission: the read permission each new upload starts with. Set to Signed URLs only, new files need a signed URL while the files you already have keep their own setting. Videos are not affected: they always follow Read access.

Uploading and changing files is controlled by your keys, not by a setting: anyone with your public key can upload, and changing or deleting a file through the API needs a request signed with your private key.

Authentication Tokens

Requests signed with your private key are permitted to perform any operation on any file. You may wish to grant more granualar permissions without allowing public access to your files. For this, you can generate authentication tokens.

Authentication tokens can also be used to sign requests, but include restrictions on what permissions the request has. They may also specify an expiry date, allowing you to grant elevated permissions for a limited time only.

Our node library includes a function for generating such tokens, but you can do so manually using JWT. To create an authentication token, follow the steps described in the API documentation, but additionally include a payload when signing the token. The payload should be a JSON object, including the following keys: