API Authentication
When integrating with the Adaptive Catalog API, there are currently two approaches.
If each of your users / companies using the integration will have their own Adaptive Catalog instance, then you simply need to have them set up an API key in Adaptive Catalog and enter the API key and Adaptive Catalog organization into your application. You can then generate session keys to make API requests on their behalf.
The other option is for your company to have an enterprise account with Adaptive Catalog and use your own API key. We still recommend allowing users to override your API key and organization, so that mutual customers are able to access their pre-existing data and use the full functionality of Adaptive Catalog. There are some limitation on the enterprise approach, as all of your customers will be sharing a single set of product data.
Client IDs
In order to ensure a smooth experience for all integration partners, as well as our users, Adaptive Catalog requires that integrators utilize a Client ID. This provides your own custom set of rate limits that have been previously discussed with the Adaptive Catalog team and allows us to make sure nobody is abusing the system. IP addresses / organizations found to be submitting too many requests without a client ID may be temporarily blocked from using the API.
You can request a client ID from the Adaptive Catalog team, or one will be supplied to you during initial onboarding. To utilize the Client ID, simply provide x-client-id in all of your API requests.
Generating Session Keys
When calling the APIs, you will need to provide an x-session-key and an x-organization header in all of your API calls. In order to generate a session key, you can call the Generate Session Key endpoint with the organization and API key. This will return a session key as the ID in the resulting response. To check the expiration time of the session key, simply call the Get Session Key endpoint with your session key.
Sub-Organizations
In order to support enterprise accounts for multiple organizations, we recommend using sub-organizations. A sub-organization allows you to set up extensions (integrations) with the same distributor for multiple accounts and keep the information separate. Any API call can also have x-suborganization supplied with it, which will limit the results to those of the specified sub-organization.
When creating a sub-organization using the Create Sub Organization API, we recommend using the actual companies name, but this is not required. Some of our integration partners instead choose to use a GUID in the name and store a lookup table in their own application. One thing we do request is accurate is the Country field, which should be a ISO 3-character code.