Manual: Access Tokens as Alternative to IP Whitelists & Basic Auth

Access tokens are header-based credentials that replace both basic auth and IP whitelisting for authenticating your API and content requests to Icecat – you generate, rotate, and revoke them yourself via My Icecat, with no support tickets or server-side IP configuration needed.

Managing Access Tokens

To receive and rotate your access tokens:

1. Register as a Channel Partner or Brand user.
2. Follow My Icecat > Access Tokens
3. On the Access Tokens UI you can manage and disable your tokens.

There are two types of tokens in Icecat:

1. API token – serves as replacement for both basic auth and IP whitelisting for Product Data Sheets and everything that requires basic authorization.
2. Content token – serves as replacement for both basic auth and IP whitelisting for Multimedia, Gallery and everything related to supplementary content for Data Sheets.

Notes

• Acess tokens are passed as headers which means that you cannot use them in browser. This method is created for scripts, and to perform testing you have to use special software like Postman.
• Access tokens have no TTL or expiration date and will be active until you delete them from the icecat.biz.
• Access tokens authentification is considered the safest on Icecat and is recommended for most users due to its reliance on user and security.
• You must not share access tokens with third parties as it is the same as transferring both your login and password.
• You can create as many tokens of each type as you need.

API Token

Replaces Basic Auth (usually, login and password) and IP whitelisting. Always passed as a header.

The list of assets that support api-token as authentification method:

1. XML Product Data Sheet (but not MetaXML)
2. XML Index Files
3. XML Reference Files
4. JSON Product Data Sheet (replaces static app_key)
5. CSV Product Data Sheet
6. CSV Index Files
7. Personal Catalog Files & Personal Index File
8. Selected endpoints from Brand API

Content Token

Replaces Basic Auth (usually, login and password) and IP whitelisting for Multimedia and Gallery.

• Content token can be used both as a parameter (in multimedia URLs) and as a header (in product data sheets URLs).
• It can be used as a header only together with the API token when requesting Product Data Sheet. In this case, we assign Content Token automatically to each asset’s URL that belongs to the product .
• It can also be used to add directly to the URL of the asset that belongs to the Full Icecat catalog, see examples below.

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.

app_key

Icecat also used to offer a static app_key token for the Full Icecat users to access content in JSON format.

⚠️ Considered a legacy authentification method. Please consider switching to dynamic tokens.

• Used only in JSON API.
• It should be added to the URL in the following way &app_key=….
• It is mandatory for Full Icecat users to access JSON files, but may be replaced with api_token. 
• It can be used for browser-to-server & server-to-server calls.
• Requires IP whitelisting.

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 Use the Tokens?

Examples for API 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 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 for 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}'