Marketcheck Home

Authentication

Authentication methods for MarketCheck API access.

Prerequisites

  1. MarketCheck account, you can sign up at MarketCheck Universe
  2. Subscription to an API package
    • Free trial available, but requires explicit subscription

Generate Credentials

To access the MarketCheck API, you need to generate API credentials. Follow these steps:

  1. Log in to your MarketCheck Universe account
  2. Navigate to the API Keys section
  3. Generate a new API key
  4. This generates a unique tuple of credentials
    • API Key: A unique key used to authenticate requests
    • Client Secret: A secret used (in conjunction with the API key) to obtain OAuth 2.0 access tokens
For non-production and credentials to be shared with vendors, partners or external developers, please add expiration dates to the credentials. This ensures security and control over access.
You can restrict the credentials to few endpoints or IP addresses for enhanced security. This is recommended for production environments.

Authentication Overview

MarketCheck API supports two primary authentication methods: API Key and OAuth 2.0. Both methods ensure secure access to the API endpoints, you can choose the one that best fits your use case.

API Key

  • The simplest authentication option, uses an API key in the query string parameter
  • Include Parameter: api_key in all the API requests. Value is the API key generated in the previous step.
request.js
import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/listing/car/3FTTW8M34RRA21879-b4178158-1a02',
  params: {api_key: 'YOUR_API_KEY'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

OAuth 2.0

Exchange your API credentials - API key and client secret for a time-limited access token using the client credentials flow.

Generate Access Token

First generate new access token using the API key and client secret. This token is then used to authenticate API requests.

request.js
import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/oauth2/token',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    grant_type: 'client_credentials',
    client_id: 'YOUR_API_KEY',
    client_secret: 'YOUR_CLIENT_SECRET'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Access API with Token

Use the access token in the Authorization header for subsequent API requests.

request.js
import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/oauth/v2/listing/car/3FTTW8M34RRA21879-b4178158-1a02',
  headers: {Accept: 'application/json', Authorization: 'Bearer YOUR_ACCESS_TOKEN'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}
OAuth 2.0 requests use a different base path: /oauth/v2/ instead of /v2/. For brevity, this documentation shows /v2/ in examples, but OAuth users should replace it with /oauth/v2/

Access Token Management

  • Access tokens are valid for a limited time (default 6 hours)
  • Once expired, you need to generate a new token, as refresh tokens are not supported

OAuth2 Token Lifecycle Management

MarketCheck provides endpoints to manage your OAuth2 tokens, allowing you to list active tokens and revoke them when needed. This is useful for security management and cleaning up unused tokens.

List Active Tokens

Retrieve a list of active OAuth2 tokens for your credentials.

Query Parameters:

ParameterRequiredDescription
api_keyYesYour OAuth2 client ID
nextNoOffset token for pagination
request.js
import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/oauth2/tokens',
  params: {api_key: 'YOUR_API_KEY'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Revoke Tokens

Revoke one or more OAuth2 tokens to immediately invalidate them.

Request Body:

FieldRequiredDescription
client_idYesYour OAuth2 client ID (API key)
client_secretYesYour OAuth2 client secret
access_tokensYesArray of access tokens to revoke (maximum 15 tokens per request, must be non-empty, each token must be unique)
Tokens can only be revoked if they were generated using the same client_id and client_secret provided in the revocation request. Tokens from different credentials will be ignored.
request.js
import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.marketcheck.com/oauth2/tokens/revoke',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  data: {
    client_id: 'YOUR_API_KEY',
    client_secret: 'YOUR_CLIENT_SECRET',
    access_tokens: ['token1', 'token2']
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

See Also