Signed uploads
On this page
With signed uploads, you get to control who can and when can upload files to
one of your Uploadcare projects. 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 both File Uploader,
jQuery widget, 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.
- Go to your Dashboard and select an existing project or create a new one.
- 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 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 with two parameters:
YOUR_SECRET_KEY
— a generated key.expire
— an expiration time message (string).
Here's how to make the signature
on your backend:
import { generateSecureSignature } from '@uploadcare/signed-uploads'
// by the expiration timestamp in milliseconds since the epoch
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
expire: Date.now() + 60 * 30 * 1000 // expire in 30 minutes
})
// by the expiration date
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
expire: new Date("2099-01-01") // expire on 2099-01-01
})
// by the lifetime in milliseconds
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
lifetime: 60 * 30 * 1000 // expire in 30 minutes
})
javascript
Expiration
The expire
string sets the expiration date and time or duration for a
signature
. It has a Unix time format.
The expire
function in the Python example above adds a certain duration after
the generation time. In this case, 30 minutes:
# Expire in 30 min, e.g., 1454903856
expire = int(time.time()) + 60 * 30
python
Signed upload example
To generate a signed upload, you need to pass 3 parameters:
YOUR_PUBLIC_KEY
, which you can get from API keyssignature
expire
Request:
curl -F "YOUR_PUBLIC_KEY=caa9d29da887ee88ffe6" \
-F "signature=46f70d2b4fb6196daeb2c16bf44a7f1e" \
-F "expire=1454903856" \
-F "file=@image.jpg" \
"https://upload.uploadcare.com/base/"
bash
Response:
{
"file": "c0d776d4-8c8e-47df-9e92-03b68b99c2ba"
}
json
To work with File Uploader, specify the secure signature and secure expire options.
To work with jQuery widget, specify respective 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:
[HTTP 400] 'signature' is required.
json
[HTTP 400] 'expire' is required.
json
If expire
is not a valid Unix timestamp:
[HTTP 400] 'expire' must be a UNIX timestamp.
json
If your signature
has expired, i.e., expire < now
:
[HTTP 403] Expired signature.
json
If signature
is incorrect:
[HTTP 403] Invalid signature.
json