Marketcheck API Security — OAuth 2.0

Marketcheck APIs support two modes of authenticating your application with the API

1. API Key
2. OAuth 2.0 access token

In this article we will discuss how to obtain and use both of them.

API Key

When you login and have subscribed to one of packages at https://marketcheck.com you can navigate to “My Account > API_KEY” page to get your api key.

https://www.marketcheck.com/api_key

You can use this API key to make API calls, by providing this API key in request url as a query string parameter.

curl --request GET 'https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=p7olRU7eKaKXIQLetIbbTqxMYnRFA1kz&car_type=used'

This is an easier interface to authenticate with API, specially if your API key is going to be used or deployed in a secure environment and only handful of people have access to it.

However if your API key is not secure and is used on client side in the browser or some application then it becomes a risk, as it can be read in various ways and used to make API calls which then you’ll be charged for. Such compromised API key can be rotated but this solves the problem temporarily. And once API key is rotated it has to be changed in all instances of your application, which is not efficient. Here the OAuth 2.0 type authentication fits better.

OAuth 2.0

In this type of authentication you can exchange your API key and Client Secret for an access_token, which you can then use to make API calls. This access_token is valid for limited time and can be easily deleted to block the API access with it.

Generate an access_token

First you’d need to acquire an access_token. For acquiring token you need a valid API key and client secret. Both can be obtained after logging into your account at https://www.marketcheck.com/api_key.

When you make an API call to request a token, it’s a good practice, and is recommended by the OAuth 2.0 specification to pass the api_key and client_secret values as an HTTP-Basic Authentication header, as described in IETF RFC 2617. To do this, you must base64-encode the result of joining the two values together with a colon separating them.

In pseudo-code:

result = Base64Encode(concat('p7olRU7eKaKXIQLetIbbTqxMYnRFA1kz', ':', 'MPWdRQasReGyQwKl'))

So the curl would look like —

curl --location --request POST 'http://marketcheck-prod.apigee.net/oauth/token/access' \
--header 'Authorization: Basic cDdvbFJVN2VLYUtYSVFMZXRJYmJUcXhNWW5SRkExa3o6TVBXZFJRYXNSZUd5UXdLbA==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'expires_in=600000'

Or without base64 encoding them, it would look like —

curl --location --request POST 'http://marketcheck-prod.apigee.net/oauth/token/access' \
-u 'p7olRU7eKaKXIQLetIbbTqxMYnRFA1kz:MPWdRQasReGyQwKl' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'expires_in=600000'

Here request body has 2 parameters — grant_type and expires_in.

Per the OAuth 2.0 specification, the grant type must be supplied with requests for access tokens. So it must be x-www-form-urlencoded and specified in the request body. Marketecheck API supports only one grant_type at the moment and that is client_credentials

expires_in indicates how long the token should remain valid for (in milliseconds). This is an optional parameter. The default value of this is 1800000 (30 minutes). It is not recommended to have very high expiry time on these tokens as well. An access_token can at max be valid for 6 hrs. Any value beyond that in expires_in parameter results in token expiry set at 6 hrs.

On success you would get a response that would look like following —

{
"organization_name":"marketcheck",
"token_type":"BearerToken",
"issued_at":"1600685261822",
"access_token":"6gnJwuAF8WATCrIjQtLiEUo7pjn5",
"scope":"",
"expires_in":"599",
"status":"approved"
}

Here in the response you get an access_token which you can use to access the API. You also get the expires_in — time remaining (in seconds) till this token expires.

Access the API

Once you have the access_token, you can use it in the Authorization header to access the API —

curl --location --request GET 'https://marketcheck-prod.apigee.net/oauth/v2/search/car/active?car_type=used' \
--header 'Authorization: Bearer 6gnJwuAF8WATCrIjQtLiEUo7pjn5'

Please note : OAuth 2.0 authentication API requests are served via a proxy with a base path of /oauth. Please take a note of the change in the base path of the request above.

The response would contain few useful headers like —

1. token_status — Describing current token status used in the request
2. expires_in — Number of seconds this token is still valid for

Delete an access_token

If the token has served its purpose and its expiry is long away or its compromised and you need to block it then you can invoke this endpoint to delete the said token

curl --location --request POST 'http://marketcheck-prod.apigee.net/oauth/token/delete' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'access_token=6gnJwuAF8WATCrIjQtLiEUo7pjn5'

POST the access_token to /delete endpoint in x-www-form-urlencoded request body. Once a token is deleted, it would take API approximately 180 sec to completely block the access for said token.

Conclusion

These OAuth tokens are light weight than the API key to block / delete. So using them instead of API keys in an insecure environment makes sense. To further secure your access to the API, you can have a reverse proxy on your end that controls API access or does the session management to invalidate the suspicious requests.