REST API Requests and Authentication
- Requests
- Authentication
Uploadcare.Simple
auth schemeUploadcare
auth scheme
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 apublic_key:signature
pair, where yoursecret_key
is used to derivesignature
but is not included in every request itself.- You MUST also provide the
Date
header formatted like in the example below (timezone must be alwaysGMT
) 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.