Accessing the API¶

The Consumer Intelligence API uses OAuth 2.0 client access tokens to authenticate requests coming from your server. To access our API, you will exchange your client's API credentials for a short-lived access token, and include the token in all calls to our API.

Prerequisites

Before proceeding to make authenticated API calls, make sure you have a client.

Get your API credentials¶

Soon after you've applied for access, you will receive your API credentials.

Your client ID will be sent to your email.
Your client secret will be sent as an SMS to your phone.

Storing your client secret securely

Your client secret is private and should not be shared with anyone outside your organization. It should be stored securely, and never be exposed publicly in client-side code or in public git repositories.

Regenerating the client secret¶

Should you lose access to your client secret, or suspect that it might be leaked, you can generate a new secret. Currently, this is only possible by contacting us or your key account manager.

Once a new secret is generated, you will receive a new SMS with a new client secret, the old client secret is immediately invalidated. You can only have one active secret at a time.

Careful regenerating the client secret in production

If you are regenerating the client secret for a client in production, we recommend planning this thoroughly to ensure your systems availability during the migration. Be ready to update your client secret values to the new one across your codebase and services immediately after regeneration.

Get an access token¶

The access token allows you to authenticate with your client, authorizing access to all data and functionality within your client. The token is obtained via the standard OAuth 2.0 client credentials grant, using the API credentials and the corresponding OAuth URL for the environment of your client. You can leverage this example to generate an access token yourself, but we recommend following our best practice to use an existing OAuth library in production.

With your client ID and client secret, you can pass these as authorization headers to the OAuth token URL, which can be found in the Environments section of the API docs.

Token request example

curl {OAUTH_TOKEN_URL} \
    -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials&scope=bci" \
    -u "{YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET}"

After requesting the token URL as described above, you'll receive a response containing your access token. This access token should be cached on your server or stored in one of your datastore's until it expires and subsequently needs to be refreshed.

Token response example

{
  "access_token": "{YOUR_ACCESS_TOKEN}",
  "expires_in": 3600,
  "scope": "bci",
  "token_type": "bearer"
}

Keep your access token secret

As with the client secret, the access token must be kept secret.

Best practice? Use an existing library to handle authentication¶

Since our API implements the OAuth 2.0 specification without any modifications, you can use a number of OAuth libraries to manage the authentication process for you. We recommend this route over rolling your own implementation, as these are usually battle tested and well maintained. You can refer to this overview of some of the libraries available in common programming languages.

Refreshing access tokens¶

The access token expires every hour, as described by the expires_in key in the access token response. Once your token expires, your server should repeat the process to obtain a new access token. OAuth libraries can help manage this process for you.

Access the API with the access token¶

With your access token ready, you can now start accessing the Consumer Intelligence API. All API requests towards your client needs to be authenticated via a bearer authentication header.

Client-wide resource request example

curl {API_URL}/consumers \
    -H "Authorization: Bearer {YOUR_ACCESS_TOKEN}" \
    -H "Content-Type: application/json"

You can grap the API URL from the Environments section of the API docs.