GraphQL Storefront API: Private Tokens and a Stronger Security Model

BigCommerce recently introduced private tokens as a new authentication standard for requests to the GraphQL Storefront API. In this walkthrough, we'll summarize the purpose of private tokens and make sure you know what the implications are for your existing and future integrations with the platform.

Going forward, the standard storefront token is intended only for client-side requests to the GraphQL API (requests made directly from a user's browser), while a private token will be required for server-to-server scenarios.

This change marks an improvement in the security model of the storefront API, in two respects:

• A clear separation in the intended use cases for tokens reduces the possibility of a token meant for a client-side application being used in an exploitive way.

• Private tokens have a more granular authorization model, using scopes to limit their level of access.

The previous pattern

Until now, the same storefront token type — created via the REST Management API with POST /v3/storefront/api-token — has been used in both client-side and server-side scenarios. The token is bound to one or more channels and an expiration date, and optionally to a list of allowed_cors_origins when it's intended for browser use. The same token type serves as the Bearer value for the Authorization header in any GraphQL Storefront API requests.

• Client-side requests: Browser-originating requests in client-side applications must include a storefront token that was created with an appropriate allowed_cors_origins value. Individual customer context in this kind of request is tracked via a storefront session cookie, in scenarios where same origin is guaranteed (such as client-side scripts in a Stencil storefront).

• Server-side requests: "Stateless" requests made from a server-side application use the same type of token, but with no required allowed_cors_origins value. Customer context is tracked via a separate Customer Access Token (CAT) — issued when a customer authenticates and sent in the X-Bc-Customer-Access-Token header.

The new pattern

The two scenarios described above continue to function in the same way; only the Bearer token type has changed for server-side scenarios.

Client-side: unchanged

Standard storefront tokens remain created via POST /v3/storefront/api-token, bound to channels and CORS origins, and used to power browser-based GraphQL requests exactly as they do today. If your storefront talks to the GraphQL Storefront API from the browser — Stencil or otherwise — nothing about that flow changes.

Server-side: the new private token

The general server-side workflow, including the use of CATs for customer context, also remains the same. However, a new REST endpoint, POST /v3/storefront/api-token-private, issues private tokens for server-side requests.

The REST request body looks familiar — channel binding and expiration are the same — with one addition: every private token must declare its scopes.

Once you have a private token, you use it the same way you use a standard storefront token — via a "Bearer" value in the Authorization header:

Customer Access Tokens work with private tokens exactly as they do with storefront tokens today. If your server-side code already authenticates customers and forwards their access token in the X-Bc-Customer-Access-Token header, that pattern carries over unchanged.

Scopes

Scopes restrict which GraphQL fields a given private token can read or mutate. Three are available at launch:

• Unauthenticated — Store, channel, catalog, products, content, cart, checkout (excluding nested order data), wishlist create/public, analytics, payment, and newsletter operations.

• Customer — Customer identity, orders, login/logout, session sync, registration, customer wishlists, cart assignment, and order messages.

• B2B — Company operations, such as registerCompany.

What do I need to do?

For any client-side applications that integrate with the GraphQL Storefront API, no action is required.

Applications using server-side requests to the storefront API should rotate to a private token created with the appropriate scope(s). No further changes to request flow or structure are necessary. (Note that this includes headless storefronts where GraphQL requests occur in a server-side layer.)

There are two deprecation dates to be aware of as you update server-side applications:

June 30, 2026 — First deprecation wave

After this date, newly issued storefront tokens can no longer be used for server-to-server calls. If your application programmatically creates storefront tokens on demand and uses them from a backend, this is the date by which it must be issuing private tokens instead.

March 31, 2027 — Second deprecation wave

After this date, the same restriction extends to pre-existing storefront tokens. Any long-lived standard storefront token still being used server-side will stop working as intended. Applications that issued a storefront token once and have been using it from a backend ever since must rotate to a private token by this date.

Implications for Catalyst

Catalyst storefronts perform GraphQL Storefront API requests from the Next.js server-side layer.

• New Catalyst storefronts: The Catalyst storefront provisioning process now issues private tokens. Sandbox storefronts and local development environments provisioned from that point forward will be on the new pattern by default — no merchant action required. When taking your storefront to production, make sure you are using the private token endpoint to generate a value for BIGCOMMERCE_STOREFRONT_TOKEN, using the scopes Unauthenticated and Customer.

• Existing Catalyst storefronts: Merchants running Catalyst today are using a standard storefront token server-side. To stay ahead of the March 31, 2027 second deprecation wave, those merchants will need to rotate the BIGCOMMERCE_STOREFRONT_TOKEN value to a private token before the deadline. Plan to provision a private token with the scopes Unauthenticated and Customer, update the storefront's environment configuration, and redeploy.

The Catalyst Unauthenticated Token

Note that Catalyst 1.7 also introduces support for a second private token value, stored in the environment variable BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN. This optional value should contain a token generated only with the Unauthenticated scope and is used exclusively for the new GraphQL proxy that allows approved client-side libraries to make GraphQL Storefront API requests. This proxy system allows for first-party use of libraries like checkout-sdk-js in a secure way.

What about customer impersonation tokens?

Developers who are well familiar with the GraphQL Storefront API may recognize the use case for private tokens as similar to that for the existing customer impersonation token, which is exclusively for server-side use and has the elevated ability to impersonate any customer on the store using an X-Bc-Customer-Id header.

Customer impersonation tokens remain a valid type of Bearer token for storefront API requests, and their behavior remains unchanged. Note, however, that this type of token is extremely sensitive due to its elevated access level and is considered a legacy approach. Using private tokens in combination with CATs is a safer approach with more limited customer access.

The final word

Private tokens, and the deprecation of standard storefront tokens for server-side applications, provide a clearer segmentation of integration use cases, while scopes provide a more granular authorization model. This new pattern doesn't change anything about the general flow and structure of GraphQL Storefront API requests. For your server-side integrations, make sure to rotate your credentials to the new private token type to keep your applications running smoothly!

Key Resource: See the developer documentation for Storefront API tokens.