Skip to main content

Authorization & sessions

Operating modes​

The Storefront API can be used in four different operating modes:

  • NO_SESSION - Stateless and primarily used to populate your own catalog cache. Must be used server-side only.
  • SESSION - Stateful and used to act on behalf of a shopper. Upon the first request using the base session token, you will receive a new session token to use in subsequent requests. When Querying Centra in this mode, all data returns will be based on the market and pricelist of the session. This includes translations to the session language, if they exist.
  • LOGGED_IN - Sub-mode of SESSION, active for any logged-in customer.
  • SHARED_SECRET - Sub-mode of SESSION. Used when you need to act on behalf of a shopper, but perform actions that the shopper themselves shouldn't access. This separate token can be found in your plugin configuration, and should be passed in the x-shared-secret header.

Get the data you need, always​

The API is designed to allow you to keep as little state as possible on the frontend

  • All the mutations affecting the selection will always return the selection and session in the response, allowing you to always be able update your frontend components to reflect the last saved state in Centra. So no need for an extra query to refresh your mini cart and session state.
  • All lists return pagination information.
  • DisplayItem.filters reflect which filters are available and which have been applied.

Separation of concerns with session and no session mode​

The Storefront API can be configured in two different modes, depending on the use case. Both modes require you to send an Authorization with the Bearer token from the plugin. One plugin can only be configured to operate in one specific mode.

NOTE: When you are querying data using a session scoped token, the data will always be returned based on the current market and price list. The returned information will be in the language set for the current session if available, falling back to the default language if not.

When using a no session scoped token you will need to provide the request information on each request (languageCode, market or pricelist) to get this result. This allows you to effectively build a cache using the key or key(s) most suitable for you.

Session mode​

Session mode allows users to perform cart, checkout and post-checkout operations and browse the catalog based on the market, price list and language of the shopper’s session. This mode also allows customers to login. Upon the first request using the bearer token from the admin you will receive a new token back for further use for the current shopper. Currently this is the only mode you can use in order to make a purchase. This mode is allowed to be used client-side(*).

(*) Certain fields and operations require you to send an additional shared secret. If a shared secret is provided only server-side, consumption of the API is allowed. The plugin can also be configured to only be allowed to be consumed server-side.

No session mode​

This mode is completely stateless and only exposes data in order for consumers to build their own cache. This mode is only accessible server side, and consuming the API in this mode should only be done in order to populate your cache, not as a means to access all data from a middleware or such.

Last updated on