Upload control with signed uploads

Signed uploads allow you to control who can upload files to your Uploadcare project and when. You need to generate a signature on your backend, and a trusted user should use this signature to upload a new file. It works with File Uploader, jQuery File Uploader (deprecated), and Upload API.

Turning signed uploads on

Signed uploads can be turned on and off to an Uploadcare project, because it has a dedicated storage, Public and Private keys, and security settings.

1. Go to your Dashboard and select an existing project or create a new one.
2. Click Enable next to Signed Uploads in the uploading settings.

From now on, every request to Upload API should include a signature part. However, you’ll still be able to upload files to your project via the Dashboard.

Signature generation

The signature string is sent along with your upload request. To generate it, you need the secret key of your Uploadcare project, which you can get from the API keys section.

The signature is an HMAC-SHA256 hash, hex-encoded:

• Key: your project’s secret key
• Message: the expire value as a string

The output is a hex-encoded digest. Here’s how to generate the signature on your backend:

1
import { generateSecureSignature } from '@uploadcare/signed-uploads'
2
3
// by the expiration timestamp in milliseconds since the epoch
4
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
5
  expire: Date.now() + 60 * 30 * 1000 // expire in 30 minutes
6
})
7
8
// by the expiration date
9
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
10
  expire: new Date("2099-01-01") // expire on 2099-01-01
11
})
12
13
// by the lifetime in milliseconds
14
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
15
  lifetime: 60 * 30 * 1000 // expire in 30 minutes
16
})

Expiration

The expire value is a Unix timestamp in seconds that defines when the signature expires. A common mistake is passing milliseconds instead of seconds — this will cause every upload to fail with [HTTP 400] 'expire' must be a UNIX timestamp.

The expire function in the Python example above adds a certain duration after the generation time. In this case, 30 minutes:

1
# Expire in 30 min, e.g., 1454903856
2
expire = int(time.time()) + 60 * 30

Signed upload example

To generate a signed upload, you need to pass 3 parameters:

• YOUR_PUBLIC_KEY
• signature
• expire

Request:

$
curl -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" \
>
     -F "signature=YOUR_SIGNATURE" \
>
     -F "expire=YOUR_EXPIRE" \
>
     -F "file=@image.jpg" \
>
     "https://upload.uploadcare.com/base/"

Response:

1
{
2
  "file": "c0d776d4-8c8e-47df-9e92-03b68b99c2ba"
3
}

To work with File Uploader, specify the secure signature and secure expire options.

Possible errors

Both signature and an active expire are required for every upload request and should be valid. The list of possible errors:

1
[HTTP 400] 'signature' is required.

1
[HTTP 400] 'expire' is required.

If expire is not a valid Unix timestamp:

1
[HTTP 400] 'expire' must be a UNIX timestamp.

If your signature has expired, i.e., expire < now:

1
[HTTP 403] Expired signature.

If signature is incorrect:

1
[HTTP 403] Invalid signature.