BigCommerce lately launched non-public tokens as a brand new authentication commonplace for requests to the GraphQL Storefront API. On this walkthrough, we’ll summarize the aim of personal tokens and ensure you know what the implications are on your present and future integrations with the platform.
Going ahead, the usual storefront token is meant just for client-side requests to the GraphQL API (requests made straight from a person’s browser), whereas a personal token might be required for server-to-server situations.
This modification marks an enchancment within the safety mannequin of the storefront API, in two respects:
-
A transparent separation within the supposed use circumstances for tokens reduces the potential for a token meant for a client-side software being utilized in an exploitive approach.
-
Non-public tokens have a extra granular authorization mannequin, utilizing scopes to restrict their stage of entry.
The earlier sample
Till now, the identical storefront token kind — created by way of the REST Administration API with POST /v3/storefront/api-token — has been utilized in each client-side and server-side situations. The token is certain to a number of channels and an expiration date, and optionally to a listing of allowed_cors_origins when it is supposed for browser use. The identical token kind serves because the Bearer worth for the Authorization header in any GraphQL Storefront API requests.
-
Consumer-side requests: Browser-originating requests in client-side purposes should embody a storefront token that was created with an applicable
allowed_cors_originsworth. Particular person buyer context in this sort of request is tracked by way of a storefront session cookie, in situations the place similar origin is assured (comparable to client-side scripts in a Stencil storefront). -
Server-side requests: “Stateless” requests constituted of a server-side software use the identical kind of token, however with no required
allowed_cors_originsworth. Buyer context is tracked by way of a separate Buyer Entry Token (CAT) — issued when a buyer authenticates and despatched within theX-Bc-Buyer-Entry-Tokenheader.
The brand new sample
The 2 situations described above proceed to operate in the identical approach; solely the Bearer token kind has modified for server-side situations.
Consumer-side: unchanged
Customary storefront tokens stay created by way of POST /v3/storefront/api-token, certain to channels and CORS origins, and used to energy browser-based GraphQL requests precisely as they do right this moment. In case your storefront talks to the GraphQL Storefront API from the browser — Stencil or in any other case — nothing about that stream modifications.
Server-side: the brand new non-public token
The final server-side workflow, together with the usage of CATs for buyer context, additionally stays the identical. Nevertheless, a brand new REST endpoint, POST /v3/storefront/api-token-private, points non-public tokens for server-side requests.
The REST request physique appears to be like acquainted — channel binding and expiration are the identical — with one addition: each non-public token should declare its scopes.
Upon getting a personal token, you utilize it the identical approach you utilize a typical storefront token — by way of a “Bearer” worth within the Authorization header:
Buyer Entry Tokens work with non-public tokens precisely as they do with storefront tokens right this moment. In case your server-side code already authenticates clients and forwards their entry token within the X-Bc-Buyer-Entry-Token header, that sample carries over unchanged.
Scopes
Scopes limit which GraphQL fields a given non-public token can learn or mutate. Three can be found at launch:
-
Unauthenticated
-
Buyer
-
B2B
registerCompany.
What do I have to do?
For any client-side purposes that combine with the GraphQL Storefront API, no motion is required.
Functions utilizing server-side requests to the storefront API ought to rotate to a personal token created with the suitable scope(s). No additional modifications to request stream or construction are mandatory. (Be aware that this consists of headless storefronts the place GraphQL requests happen in a server-side layer.)
There are two deprecation dates to pay attention to as you replace server-side purposes:
June 30, 2026 — First deprecation wave
After this date, newly issued storefront tokens can now not be used for server-to-server calls. In case your software programmatically creates storefront tokens on demand and makes use of them from a backend, that is the date by which it should be issuing non-public tokens as an alternative.
March 31, 2027 — Second deprecation wave
After this date, the identical restriction extends to pre-existing storefront tokens. Any long-lived commonplace storefront token nonetheless getting used server-side will cease working as supposed. Functions that issued a storefront token as soon as and have been utilizing it from a backend ever since should rotate to a personal token by this date.
Implications for Catalyst
Catalyst storefronts carry out GraphQL Storefront API requests from the Subsequent.js server-side layer.
-
New Catalyst storefronts: The Catalyst storefront provisioning course of now points non-public tokens. Sandbox storefronts and native growth environments provisioned from that time ahead might be on the brand new sample by default — no service provider motion required. When taking your storefront to manufacturing, ensure you are utilizing the non-public token endpoint to generate a worth for
BIGCOMMERCE_STOREFRONT_TOKEN, utilizing the scopesUnauthenticatedandBuyer. -
Present Catalyst storefronts: Retailers working Catalyst right this moment are utilizing a typical storefront token server-side. To remain forward of the March 31, 2027 second deprecation wave, these retailers might want to rotate the
BIGCOMMERCE_STOREFRONT_TOKENworth to a personal token earlier than the deadline. Plan to provision a personal token with the scopesUnauthenticatedandBuyer, replace the storefront’s surroundings configuration, and redeploy.
The Catalyst Unauthenticated Token
Be aware that Catalyst 1.7 additionally introduces help for a second non-public token worth, saved within the surroundings variable BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN. This optionally available worth ought to include a token generated solely with the Unauthenticated scope and is used completely for the brand new GraphQL proxy that enables accredited client-side libraries to make GraphQL Storefront API requests. This proxy system permits for first-party use of libraries like checkout-sdk-js in a safe approach.
What about buyer impersonation tokens?
Builders who’re nicely conversant in the GraphQL Storefront API could acknowledge the use case for personal tokens as just like that for the prevailing buyer impersonation token, which is completely for server-side use and has the elevated potential to impersonate any buyer on the shop utilizing an X-Bc-Buyer-Id header.
Buyer impersonation tokens stay a legitimate kind of Bearer token for storefront API requests, and their habits stays unchanged. Be aware, nonetheless, that any such token is extraordinarily delicate resulting from its elevated entry stage and is taken into account a legacy method. Utilizing non-public tokens together with CATs is a safer method with extra restricted buyer entry.
The ultimate phrase
Non-public tokens, and the deprecation of normal storefront tokens for server-side purposes, present a clearer segmentation of integration use circumstances, whereas scopes present a extra granular authorization mannequin. This new sample does not change something concerning the normal stream and construction of GraphQL Storefront API requests. On your server-side integrations, make sure that to rotate your credentials to the brand new non-public token kind to maintain your purposes working easily!
Key Useful resource: See the developer documentation for Storefront API tokens.
