Authentication

apiKeyAuth

Every request made to https://api.uploadcare.com/ MUST be signed. HTTPS SHOULD be used with any authorization scheme.

Requests MUST contain the Authorization header defining auth-scheme and auth-param: Authorization: auth-scheme auth-param.

Every request MUST contain the Accept header identifying the REST API version: Accept: application/vnd.uploadcare-v0.7+json.

There are two available authorization schemes:

• For production: Uploadcare, a scheme where a signature, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend.
• For quick tests: Uploadcare.Simple, a simple scheme where your Secret API Key MUST be specified in every request’s auth-param.

Uploadcare

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 in RFC2822 format with the time zone set to GMT (see the example below).
• The date you provide MUST NOT exceed the 15-minute offset from the server time of the API endpoint.

1
Accept: application/vnd.uploadcare-v0.7+json
2
Date: Fri, 30 Sep 2016 11:10:54 GMT
3
Authorization: Uploadcare public_key:6ff75027649aadd4dc98c1f784444445d1e6ed82

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 your project’s secret_key.

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

1
import time
2
import hashlib
3
import hmac
4
from email import utils
5
6
# Specifying the project’s key
7
SECRET_KEY = 'YOUR_SECRET_KEY'
8
9
# Specifying request type
10
verb = 'GET'
11
12
# Calculate [md5](https://en.wikipedia.org/wiki/MD5) checksum for the request's HTTP body.
13
# Note: Taking into account that in our example, we are sending an HTTP GET request,
14
# and the request does not have anything in its HTTP body, we use an empty string as an input to the md5 hash function.
15
# If we were to send an HTTP POST request with, for example, JSON in the request's body,
16
# we would have to pass the JSON as the input to the md5 hash function.
17
content_md5 = hashlib.md5(b'').hexdigest()
18
19
# Content-Type header
20
content_type = 'application/json'
21
22
# Current time, e.g. 1541423681
23
timestamp = int(time.time())
24
# Date header ('Mon, 05 Nov 2018 13:14:41 GMT')
25
date_header = utils.formatdate(timestamp, usegmt=True)
26
27
# The request URI
28
uri = '/files/?limit=1&stored=true'
29
30
# Forming the final string: concatenating
31
sign_string = '\n'.join([verb, content_md5, content_type, date_header, uri])
32
33
# Calculating the signature,
34
# the result may look like this: "3cbc4d2cf91f80c1ba162b926f8a975e8bec7995"
35
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.7+json' \
>
    -H 'Date: Mon, 05 Nov 2018 13:14:41 GMT' \
>
    -H 'Authorization: Uploadcare YOUR_PUBLIC_KEY:SIGNATURE' \
>
    'https://api.uploadcare.com/files/?limit=1&stored=true'

Uploadcare.Simple

Note: We DO NOT recommend using this authentication method in production.

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

1
Accept: application/vnd.uploadcare-v0.7+json
2
Authorization: Uploadcare.Simple public_key:secret_key