Frequently asked questions and best practices about what types of tokens you need to request to authenticate to Commerce Layer API and how to manage them
Check our documentation for more information about this topic:
Frequently asked questions
When should I request an integration token and when a sales channel token instead?
The decision to request an integration token or a sales channel token depends on your application's needs and the specific operations you intend to perform.
You should request an token in the following cases:
Backend services — when building backend services that handle business logic and interact with the Commerce Layer API without being tied to a specific sales channel.
Broad operations — when you need to deal with tasks like inventory or price management, product updates, or reporting that require access to data from various channels.
General API access — when your application needs to interact with multiple resources across various sales channels.
Always remember that integration tokens contain very sensitive information and should never be exposed externally.
You should request a sales channel token in the following case:
Frontend applications — when your application interacts directly with a specific sales channel, such as an ecommerce site or a mobile app focused on one channel only.
How long should a token last?
, sales channel tokens remain valid for 4 hours, whereas integration tokens and webapp tokens are valid for 2 hours. You can adjust the duration of these tokens in the API credentials section of the Dashboard, by selecting the specific API credentials and then clicking on the Edit button.
Sales channel tokens are public, so extending their validity won’t pose a security risk unless used for customer logins. However, these tokens contain information about stock, pricing, and other configurations that may change during their validity period. Adjust the token's duration based on how often you update stock and pricing details.
As far as integration tokens are concerned, they are generated using a secret key and have access to all the organization's information. That's why we recommend keeping their validity as short as possible for security reasons.
I keep being rate-limited on auth calls. What shall I do?
If you are getting 429 Too many requests errors when querying our authentication endpoints from your frontend or backend for frontend, it means you're hitting our API . Remember that you cannot request auth tokens more than 30 times in 1 minute for each IP address.
To avoid that, you should cache the auth token in a storage (e.g. cookies, Redis, KV), so you don’t have to ask for a new token every time you make a call. As soon as the token expires, request a new one — in this way, you will respect the rate limits (we are currently working on allowing new token requests 15 minutes before the previous one expires to avoid any risk of dealing with expired tokens — keep an eye on our to be notified about the update).
How can I refresh a token for a logged customer? When should I do that?
To avoid hitting our API , logged customers should not authenticate again if the token expires during their session. Remember that you cannot request auth tokens more than 30 times in 1 minute for each IP address.
At authentication, you should cache both the auth token and the provided in a storage (e.g. cookies, Redis, KV). When the user logs out, delete the token from the cache and it.
If you are using an external identity provider and are on an Enterprise contract, we might have another solution for you — please contact us.
A cached token that has not expired yet seems to be invalid. What happened?
If you are receiving a 401 Unauthorized error from an auth call, try generating a new auth token because a revoke could have happened on the previously used one.
How can I implement Single Sign-on (SSO) using Commerce Layer?
Feel free to follow the detailed guide we published in this blog article (use case: Commerce Layer + Next.js + Auth0).
What's the most efficient way to persist the ID of an order during user navigation?
When storing an order ID in cache, carefully choose the storage key. You should put in the key variables that combined together can generate a different order. For example, a good idea is to put the client ID and the scope in the key (e.g. cl-order-2fdsf3434-market:code:usa), so that different clients or different scopes will have a different order. This way, if the customer is logged in, you can show them their last available pending cart.
We strongly recommend you avoid dealing with unnecessary empty orders (e.g. creating a new order for every new session). The best practice is to create a new order as soon as the customer adds the first line item.
Does Commerce Layer provide a way to manage customer identity, logins, and signups?
Yes, you can leverage our Identity MFE, an identity provider microfrontend built in React that allows you to integrate your own authentication and user management system into the Commerce Layer platform. This MFE enables you to manage user signups, logins, and account settings while seamlessly connecting with Commerce Layer's services.
The Identity MFE is open-source: fork the repository and deploy it to any hosting service or use it as a reference application to build your own. A hosted version is also available for every Commerce Layer user.
Remember that tokens even if they have not expired yet for any reason (e.g. someone has imported a wrong price list and needs to revert the action). If you have not considered this scenario, you might end up with a non-expired token that is no longer valid.
Commerce Layer lets you authenticate users in your systems and use SSO with JWT so that a user is automatically verified with an identity provider of your choice when they sign in. To do that, you can leverage the with the correct assertion.
