Skip to main content
More in Learn

Authentication in Crystallize

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

Authentication ("I am who I say I am") is distinct from authorization ("I'm allowed to do what I'm trying to do"). We have a separate page regarding authorization in Crystallize.

APIs and Their Default Configuration

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

Shop API<tenant-identifier>/cart
Default authentication: PIM account access key pair

Subscription API<tenant-identifier>/subscriptions
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 access to these APIs by enabling API authentication.

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

Enable Authentication

Protecting your APIs is simple. Within the Crystallize App, click the Settings button on the left-hand side of the screen, then choose API Access. Then, for each of the APIs in question, select the “Faster - Basic authentication“ option and click Save.

We recommend “Faster - Basic authentication” 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 so that the request is authenticated. The proxy API can also intercept requests and remove any sensitive content they 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 the Crystallize APIs directly.

Order, Shop, Subscription, and PIM API Authentication

The Order, Shop, Subscription, and PIM APIs use PIM account access key pair authentication. You’ll need to set valid X-Crystallize-Access-Token-Id and X-Crystallize-Access-Token-Secret headers on requests. Visit the Access Tokens documentation to learn more.

Check Out Our Authentication Livestream

People showing thumbs up

Need further assistance?

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

Join our slack community