Skip to main content
More in Learn


Authentication is the process of recognizing a user’s identity. Inside Crystallize there are some APIs and services that you must authenticate before using it, here is a list of the APIs and services that are required to do that.

APIs and their default config

When you create a new tenant in Crystallize, you get a few APIs out of the box. The default authentication is as follows.

Search API<tenant-identifier>/search
Default authentication: no authentication

Catalogue API<tenant-identifier>/catalogue
Default authentication: no authentication

Orders API<tenant-identifier>/orders
Default authentication: PIM account access key pair

As you can see, both the Search and Catalogue APIs are open for access without authentication. This is OK for most cases, but if you store sensitive information in Crystallize, you might want to limit the access to these APIs by enabling API authentication.

When you enable API authentication, the APIs can no longer accessed publicly without secret tokens that you manage.

Enable Search and Order API authentication

Protecting your APIs is simple in Crystallize. Head over to the Settings page within Crystallize and click on “API Access“. Then for the API in question, click the “Faster - Basic authentication“ and then “Save”.

We recommend the “Faster - Basic authentication” option, for two reasons:

  1. The API speed will not be affected much, typically only adding a few extra milliseconds to the request
  2. The static token is connected with the tenant, not the PIM user, which is easier to manage in a team context

Applying authentication to API requests

When using “Faster - Basic authentication”, you need to add a X-Crystallize-Static-Auth-Token header value to each request. Here’s an example using the Fetch API in Javascript:

fetch('<tenant-identifier>/search', {
method: 'post',
headers: {
'Content-Type': 'application/json',
'X-Crystallize-Static-Auth-Token': 'insert-your-static-token-here'
body: JSON.stringify(...)

Using authenticated APIs from the frontend

Once you turn on authentication for any of these APIs, you cannot make fetch requests from the browser any longer. For each request to the API, you need to set the appropriate tokens. This will break any frontend that was relying on such requests to be executed without authentication.

After enabling authentication, each request needs to be proxied through an API which will forward the request to the Crystallize APIs, ensuring the proper tokens are added to ensure that the request is authenticated. The proxy API can also intercept the requests and remove any sensitive content it may contain, or apply rate limiting if you want to throttle the amount of requests going to Crystallize.

Examples for how to proxy requests can be found in the Service API boilerplate, and each of our boilerplates have examples of how to target the proxy API instead of hitting Crystallize APIs directly

Order and PIM API authentication

The Order API uses PIM Account access key pair authentication. You’ll need to set valid “X-Crystallize-Access-Token-Id” and ”X-Crystallize-Access-Token-Secret” headers. Visit the Access Tokens documentation to learn more.

To use these APIs you have to create a Crystallize account and create an access token then set the access token to the header to complete the authentication process.

People showing thumbs up

Need further assistance?

Ask the Crystallize team or other enthusiasts in our slack community.

Join our slack community