REST API requests and authentication
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,
If no version info is specified, a default API version is used, ver. 0.5 by now.
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.
Authorization: Uploadcare.Simple public_key:private_key
Uploadcare authentication method:
public_key:signaturepair, where your
secret_keyis used to derive
signaturebut is not included in every request itself.
- You MUST also provide the
Dateheader formatted according to RFC 2822, and the date you provide MUST NOT exceed the 15-minute offset from the server time of the API endpoint.
Dategets converted to UTC.
Date: Fri, 30 Sep 2016 11:10:54 GMT
Authorization: Uploadcare ac58a21ea143ffa4f1af:6ff75027649aadd4dc98c1f784444445d1e6ed82
signature part of the
Uploadcare authentication method
auth-param MUST be constructed from the following components,
- Request type (
- Hex md5 hash of the request body.
- 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,
# importing the needed libraries
from email import utils
from datetime import datetime
# specifying the project’s key (demo key is used in the 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('').hexdigest()
# Content-Type header
content_type = 'application/json'
# Date header
date_header = utils.formatdate(usegmt=True)
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
signature = hmac.new(SECRET_KEY, sign_string, hashlib.sha1).hexdigest()
signature is derived, it SHOULD be implemented into the request body,
-H "Content-Type: application/json" \
-H "Accept: application/vnd.uploadcare-v0.5+json" \
-H "Date: Fri, 30 Sep 2016 12:11:58 -0000" \
-H "Authorization: Uploadcare demopublickey:170e3a56f5cb70adcb25e6cddb5d34aa8620aca9" \