> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

### 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](https://app.uploadcare.com/projects/-/api-keys/) 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](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) 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.

```http
Accept: application/vnd.uploadcare-v0.7+json
Date: Fri, 30 Sep 2016 11:10:54 GMT
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](https://en.wikipedia.org/wiki/HMAC) 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:

```py
import time
import hashlib
import hmac
from email import utils

# Specifying the project’s key
SECRET_KEY = 'YOUR_SECRET_KEY'

# Specifying request type
verb = 'GET'

# Calculate [md5](https://en.wikipedia.org/wiki/MD5) checksum for the request's HTTP body.
# Note: Taking into account that in our example, we are sending an HTTP GET request,
# and the request does not have anything in its HTTP body, we use an empty string as an input to the md5 hash function.
# If we were to send an HTTP POST request with, for example, JSON in the request's body,
# we would have to pass the JSON as the input to the md5 hash function.
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:

```bash
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*.

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