REST API Requests and Authentication

REST API requests

To authenticate your account, every request made to MUST be signed. There are two available auth schemes: a simple one with intuitive auth-param and a more sophisticated and secure one that can be used for Signed Requests.

Every request MUST contain the Authorization header where auth-param differs amidst the two authentication methods,

`Authorization: auth-scheme auth-param`

Every request MAY contain the Accept header to specify the accepted data types and API version,

`Accept: application/vnd.uploadcare-v0.5+json`

If no version info is specified, a default API version is used, ver. 0.5 by now.

Uploadcare.Simple auth-scheme

With the Uploadcare.Simple authentication method, auth-param is your public_key:secret_key pair. With this scheme, your Uploadcare project secret_key gets included in every request.

Example request, Uploadcare.Simple

Accept: application/vnd.uploadcare-v0.5+json
Authorization: Uploadcare.Simple public_key:private_key

Uploadcare auth-scheme

With the Uploadcare authentication method:

  • auth-param is a public_key:signature pair, where your secret_key is used to derive signature but is not included in every request itself.
  • You MUST also provide the Date header formatted like in the example below (timezone must be always GMT) and the date you provide MUST NOT exceed the 15-minute offset from the server time of the API endpoint.

Example request, Uploadcare

Accept: application/vnd.uploadcare-v0.5+json
Date: Fri, 30 Sep 2016 11:10:54 GMT
Authorization: Uploadcare ac58a21ea143ffa4f1af:6ff75027649aadd4dc98c1f784444445d1e6ed82

Building signature

The signature part of the Uploadcare authentication method auth-param MUST be constructed from the following components,

  • Request type (POST, GET, HEAD, OPTIONS).
  • Hex md5 hash of the request body.
  • Content-Type header value.
  • Date header value.
  • URI including path and parameters.

The parameters are then concatenated in textual order using LF: every value sits in a separate line. The result is then signed via SHA1 using secret_key of your project as a key.

Take a look at the Python example of deriving signature; the example request is made to get a list of files,

import time
import hashlib
import hmac
from email import utils

# Specifying the project’s key (demo account Public API Key is used in this example)
SECRET_KEY = 'demoprivatekey'

# Specifying request type
verb = 'GET'

# Calculating md5, since we send an empty string,
# md5 calculations are performed for an empty string
content_md5 = hashlib.md5(b'').hexdigest()

# Content-Type header
content_type = 'application/json'

# Current time, e.g. 1541423681
timestamp = int(time.time())
# Date header ('Mon, 05 Nov 2018 13:14:41 GMT')
date_header = utils.formatdate(timestamp, usegmt=True)

# The request URI
uri = '/files/?limit=1&stored=true'

# Forming the final string: concatenating
sign_string = '\n'.join([verb, content_md5, content_type, date_header, uri])

# Calculating the signature,
# the result may look like this: "3cbc4d2cf91f80c1ba162b926f8a975e8bec7995"
signature =, sign_string.encode(), hashlib.sha1).hexdigest()

Once signature is derived, it SHOULD be implemented into the request body,

curl  \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Date: Mon, 05 Nov 2018 13:14:41 GMT" \
     -H "Authorization: Uploadcare demopublickey:3cbc4d2cf91f80c1ba162b926f8a975e8bec7995" \


  • All date and time strings used with the API MUST be in the ISO 8601 extended format.
  • For the pyuploadcare implementation of the Uploadcare authentication method, you may refer here.


We’re always happy to help with code, integration, and other stuff.
Search our site for more info or post your question in our Community Area.