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 following APIs are open for access without authentication by default:
The following 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:
Enabling Authentication for the Search and Catalogue APIs
In most cases, it’s OK to leave the Search and Catalogue APIs open for access. But if you store sensitive information in Crystallize, you may want to limit access by enabling authentication. This can be done within the Crystallize App. Click the Settings button on the left-hand side of the screen, then click the API Access label. For each API, you can choose between Fast - Access Token and Faster - Basic authentication. We recommend Faster - Basic authentication for two reasons:
- The API speed will not be affected much, typically only adding a few extra milliseconds to the request.
- The static token is connected with the tenant, not the PIM user, which is easier to manage in a team context.
Once you’ve made your selection, click the Save button.
Applying Authentication to API Requests
When you enable API authentication, the APIs can no longer be accessed publicly without secret access tokens that you manage. 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('https://api.crystallize.digital/<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 open-source boilerplates have examples of how to target the proxy API instead of hitting the Crystallize APIs directly.
