2. API Authentication Mechanisms

MetaDefender Cloud APIs are protected by a Basic authentication mechanism. All API users are required to include their API key in the appropriate header when communicating with the public APIs. In order to obtain your API key, follow the steps in our guide, Onboarding Process for MetaDefender Cloud API Users.

Authentication Examples

MetaDefender Cloud v2/v4 APIs

MetaDefender Cloud v2 and v4 APIs use the custom HTTP header apikey. Every request must send this header.

Successful API Authentication Request

> curl -X POST https://api.metadefender.com/v2/file -H 'apikey: YOUR_API_KEY' -H 'filename: file.zip -d @file_name.txt
> POST /v2/file HTTP/1.1
> Host: api.metadefender.com
> User-Agent: curl/7.52.1
> Accept: */*
> apikey: YOUR_API_KEY
> filename: file.zip
> Content-Length: 1859
> Content-Type: application/x-www-form-urlencoded
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Date: Wed, 23 Aug 2017 18:47:45 GMT
< Vary: Accept-Encoding
< X-Authenticated: by apikey
< X-RateLimit-For: uploadFile
< X-RateLimit-Interval: 3600
< X-RateLimit-Limit: 100
< X-RateLimit-Remaining: 98
< X-RateLimit-Reset-In: 3294s
< X-RateLimit-Used: 1
< X-Response-Time: 123ms
< Content-Length: 122
< Connection: keep-alive
 
{
"data_id":"ZDE3MDgyM0h5OGVZUjZyaWRaQkp3eFlSNnJpTy0",
"status":"inqueue",
"in_queue":12,
"rest_ip":"api.metadefender.com/v2"
}

Failed API Authentication Request

In case you provide a nonexistent API key, MetaDefender Cloud APIs will respond with a 401 Invalid API key request.

> curl -v -X POST https://api.metadefender.com/v2/file -H 'apikey: NON_EXISTING_API_KEY' -H 'filename: file.zip' -H 'samplesharing: 0'
 
> POST /v2/file HTTP/1.1
> Host: api.metadefender.com
> User-Agent: curl/7.52.1
> Accept: */*
> apikey: NON_EXISTING_API_KEY
> filename: file.zip
> samplesharing: 0
>
< HTTP/1.1 401 Invalid API key
< Content-Type: text/plain; charset=utf-8
< Date: Wed, 23 Aug 2017 18:43:42 GMT
< Vary: Accept-Encoding
< Content-Length: 0
< Connection: keep-alive
<
* Curl_http_done: called premature == 0
* Connection #0 to host api.metadefender.com left intact

MetaDefender Cloud v3 APIs

MetaDefender Cloud v3 APIs use standard HTTP header Authentication. Every request to v3 endpoints must have this header set.

Successful API Authentication Request

> curl -v "https://api.metadefender.com/v3/appinfo/64638C3FF08EECD62E2B24708CF5B5F111C05E3D" -H 'Authorization: apikey YOUR_API_KEY'
 
> GET /v3/appinfo/64638C3FF08EECD62E2B24708CF5B5F111C05E3D HTTP/1.1
> Host: api.metadefender.com
> User-Agent: curl/7.52.1
> Accept: */*
> Authorization: apikey YOUR_API_KEY
>
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Date: Wed, 23 Aug 2017 18:36:41 GMT
< ETag: "272a8-hYK6yyj7WkeqK2V1z4I3m1FFDtE"
< Vary: Accept-Encoding
< X-Authenticated: by apikey
< X-RateLimit-For: appInfo
< X-RateLimit-Interval: 3600
< X-RateLimit-Limit: 100
< X-RateLimit-Remaining: 97
< X-RateLimit-Reset-In: 3459s
< X-RateLimit-Used: 1
< X-Redis-Cache: true
< X-Response-Time: 14ms
< Content-Length: 160424
< Connection: keep-alive
 
{
"success":true,
"data":[
{
"appinfo_report_date":"2016-06-08T00:00:00.000Z",
"sha1":"64638C3FF08EECD62E2B24708CF5B5F111C05E3D"
}
]
}

Failed API Authentication Request

In case you provide a nonexistent API key, MetaDefender Cloud APIs will respond with a 404 Not Found request. The body will describe the error.

> curl -v "https://api.metadefender.com/v3/appinfo/64638C3FF08EECD62E2B24708CF5B5F111C05E3D" -H 'Authorization: apikey NON_EXISTING_API_KEY'
 
> GET /v3/appinfo/64638C3FF08EECD62E2B24708CF5B5F111C05E3D HTTP/1.1
> Host: api.metadefender.com
> User-Agent: curl/7.52.1
> Accept: */*
> Authorization: apikey NON_EXISTING_API_KEY
>
< HTTP/1.1 404 Not Found
< Content-Type: application/json; charset=utf-8
< Date: Wed, 23 Aug 2017 18:41:28 GMT
< Vary: Accept-Encoding
< Content-Length: 81
< Connection: keep-alive
<
* Curl_http_done: called premature == 0
* Connection #0 to host api.metadefender.com left intact
{
"success":false,
"error":{
"code":404008,
"messages":[
"The apikey was not found"
]
}
}