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
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.
Accept: application/vnd.uploadcare-v0.5+json Authorization: Uploadcare.Simple public_key:secret_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 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.
Accept: application/vnd.uploadcare-v0.5+json Date: Fri, 30 Sep 2016 11:10:54 GMT Authorization: Uploadcare ac58a21ea143ffa4f1af:6ff75027649aadd4dc98c1f784444445d1e6ed82
signature part of the
Uploadcare authentication method
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 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()
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"