REST API Requests and Authentication

REST API requests

To authenticate your account, every request made to https://api.uploadcare.com/ 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:secret_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 with HMAC/SHA1 using secret_key of your project.

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 = 'demosecretkey'

# 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 = hmac.new(SECRET_KEY.encode(), 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" \
     "https://api.uploadcare.com/files/?limit=1&stored=true"

Note,

  • 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.