Access Tokens as an Alternative to IP Whitelists and app_key

Access tokens are useful in token-based authentication to allow access to static assets or dynamic documents. We have two types of tokens:

API Access Token is useful to access XML and JSON files.

• It is used as an alternative for the user’s IP whitelisting 
• It can be used in a header while downloading JSON or XML from server to server. 
• It should be added in a header in the following way: 

–header ‘Api-Token: ……… 

• It can be used as an alternative for app_key while downloading data from server to server. 
• It is not possible to use for calls from browser to server 

Content Access Tokens are useful to access static resources like images, videos, and any other supported types of media objects.

• It is used as an alternative for the user’s IP whitelisting 
• It can be used in a header while downloading media assets from server to server. In this case, we assign Content Token automatically to each asset’s URL that belongs to the product  
• It can be used in a header, only together with the API token used in a header 
• It should be added in a header in the following way:

–header ‘Content-Token: ………  

• It can also be used to add directly to the URL of the asset that belongs to the Full Icecat catalog
• It should be added to the URL of the asset in the following way:

?content_token=………

• It can be used for calls from a browser to a server 

Further, the Icecat team checks if the usage of tokens conforms to the subscriptions of a user. Additionally, the team will monitor suspicious tokens and revoke tokens, if necessary.

Icecat also offers app_key service to Full Icecat users who are willing to download content in JSON format.

• It is ONLY used by adding at the end of the URL of the JSON call.
• It should be added to the URL in the following way &app_key=….
• It is mandatory for Full Icecat users to access JSON files. 
• It can be used for browser-to-server calls. 
• It can be used for server-to-server calls

Tokens and IP Whitelists

Furthermore, Icecat supports backward compatibility. So, we still process those calls made without tokens as usual by comparing the IP address of the request to IPs in a whitelist. In contrast, calls with Access Tokens will not be validated by checking the IP address against the whitelist. Therefore, no additional configuration is required for existing client implementations.

How to get an Access Token or app_key?

Icecat users can get Access Tokens and app_key from the Icecat portal on “My Profile”. Please note app_key is available only for Full Icecat users.

Furthermore, we will revoke unnecessary or compromised tokens via the same page. Moreover, users can create as many Access Tokens of each type as is necessary for their applications.

How to Use the Tokens?

Here is an example of the use of an API Access Token:

curl --location --request GET 'https://data.icecat.biz/xml_s3/xml_server3.cgi?product_id={product_id};lang={short_code};output=productxml' \
--header 'Api-Token: {your_api_token}'

curl --location --request GET 'https://data.icecat.biz/xml_s3/xml_server3.cgi?lang={langcode}&prod_id={mpn}&vendor={brandName}&output=productxml' \
--header 'Api-Token: {your_api_token}'

curl --location --request GET 'https://data.icecat.biz/xml_s3/xml_server3.cgi?ean_upc={gtin}&lang={langcode}&output=productxml' \
--header 'Api-Token: {your_api_token}'

Of course, you get an error if you send a non-existing or revoked API token to Icecat.

Examples for Content Access Token:

Here an example of the use of a Content Access Token at the end of the URL:

https://icecat.com/objects/1234567890.mp4?content_token={your_content_token}

Examples with both tokens:

In case you send a Content token together with API token, we will add the Content token to all media asset URLs. Below, is a code example:

curl --location --request GET 'https://data.icecat.biz/xml_s3/xml_server3.cgi?product_id={product_id};lang={short_code};output=productxml' \
--header 'Api-Token: {your_api_token}' \
--header 'Content-Token: {your_content_token}'

curl --location --request GET 'https://data.icecat.biz/xml_s3/xml_server3.cgi?lang={langcode}&prod_id={mpn}&vendor={brandName}&output=productxml' \
--header 'Api-Token: {your_api_token}' \
--header 'Content-Token: {your_content_token}'

curl --location --request GET 'https://data.icecat.biz/xml_s3/xml_server3.cgi?ean_upc={gtin}&lang={langcode}&output=productxml' \
--header 'Api-Token: {your_api_token}' \
--header 'Content-Token: {your_content_token}'

Anton Bondarenko