> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Authentication Flow Plan: B2B Developer Lesson 18 of 25 ยท 15 min ## Introduction The abstraction layer provided by the Buyer Portal, as you used in the previous lab, will handle the details of authentication with the B2B or BigCommerce GraphQL Storefront APIs automatically, based on the user's logged-in state. You will not typically need to worry about obtaining and tracking API tokens in your own code. However, it is helpful to have a baseline understanding of the API authentication flow, particularly since the Buyer Portal manages multiple tokens (for the **B2B GraphQL API** and the standard **BigCommerce GraphQL Storefront API**) as well as syncing Stencil session login. > **Info** > > If you don't want to dig into the authentication details under the hood right now, feel free to skip this section! > > Particularly if you are implementing a **headless storefront**, however, this section provides important details for making sure your Buyer Portal has a valid B2B storefront token. ## B2B GraphQL API B2B GraphQL API queries and mutations are either: * **Anonymous**, requiring no authentication token. The `login` mutation itself is an example of this. * **Authenticated**, requiring a Bearer token unique to the user. This describes most queries and mutations. It's essential that a logged-in user in the Buyer Portal have a **B2B storefront token** for use with this API. The most straightforward way to obtain one is with the user's credentials and the `login` mutation. As you'll see below, there are other methods as well. > **Info** > > All B2B GraphQL requests are made to an endpoint on a BigCommerce domain. > **Info** > > See the [B2B GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground) for details about the mutations described in this section. ## BigCommerce GraphQL Storefront API Requests to the standard BigCommerce GraphQL Storefront API include two pieces of information relevant to our discussion: * **Storefront token:** This Bearer token is required for *all* requests. It is not specific to a user but is generated by a BigCommerce API consumer. * **Customer context:** The individual user's context is provided in one of the following ways. * *Storefront session*: Only in **client-side**, **stateful** requests, the customer context is derived from the same session cookie that tracks the overall session. This makes this method viable for Stencil storefronts. * *Customer access token*: In **server-side**, **stateless** requests, a user-unique token obtained at login provides the context. As a server-side method, this is **not used by the Buyer Portal**. However, this token can be relevant for obtaining a B2B storefront token. (See below.) Because of the nature of customer context, the Buyer Portal uses two different approaches for making requests to the GraphQL Storefront API: ### Direct Requests When the storefront is **Stencil**, most requests are made directly to the storefront domain (via the `/graphql` endpoint, as standard with this API). The client-side nature of the requests allow the customer context to be provided automatically by the Stencil storefront session, as described above. In this scenario, the Buyer Portal must track a standard **storefront token** for such requests, in addition to the B2B token. ### Proxied Requests In a **headless storefront**, GraphQL Storefront API requests are *proxied* through a B2B Edition endpoint, which accepts the **B2B storefront token** and handles the proper authentication and customer context on the backend. > **Info** > > The `platform` value set in the Buyer Portal initialization scripts controls the designation of Stencil or headless. A value of "bigcommerce" indicates a Stencil storefront. > > Note that proxied requests are used for certain GraphQL Storefront API requests even in Stencil storefronts. ## Authentication Flow in Stencil In Stencil storefronts, the authentication flow must account for: * Obtaining a **B2B storefront token** for B2B GraphQL API requests * Obtaining a standard **storefront token** for BigCommerce GraphQL Storefront API requests * Logging the user in via the normal **Stencil storefront session** The Buyer Portal presents its own custom login page, which performs these major steps: 1. Credentials are passed to the B2B GraphQL API `login` mutation. 2. A successful login returns a **B2B storefront token** and a **signed JWT** (`storefrontLoginToken`). 3. The B2B storefront token is set in the session. 4. The [**Customer Login API**](/developer/docs/storefront/guides/customer-authentication/customer-login) endpoint is called, using the `storefrontLoginToken`, to log the customer into the Stencil session. 5. A side effect in the central `App` entry point is triggered, calls the B2B `storeFrontToken` mutation to obtain a standard **storefront token**, and sets it in the session. By the end of this process, the user has been logged into the Stencil storefront and has obtained tokens for both APIs. > **Info** > > See the following areas of the codebase: > > * `handleLoginSubmit` in `pages/Login/index.tsx` > * `loginInfo` in `utils/loginInfo.ts` (called in `App.tsx`) ### Rehydrating the B2B Token If the user's B2B storefront token is removed from the session or invalidated in any way, but the user is still logged into the Stencil storefront, the Buyer Portal automatically takes care of re-obtaining a token without requiring the user to provide their credentials again. 1. The [**Current Customer API**](/developer/docs/storefront/guides/customer-authentication/current-customer) endpoint is called to obtain a signed JWT verifying the logged-in user's identity. 2. The B2B `authorization` mutation is called with the JWT to obtain the B2B token. > **Info** > > See the following areas of the codebase: > > * `getCurrentCustomerInfo` and `loginWithCurrentCustomerJWT` in `utils/loginInfo.ts` ## Authentication Flow in Headless When using the Buyer Portal in a headless storefront, there are a couple of possible approaches to authentication: ### Built-in Login Page If your headless storefront presents the Buyer Portal's built-in login page, the authentication flow will be the same as described for Stencil above. The key difference is that the steps for **logging into the storefront session** and **obtaining a standard storefront token** will not be performed, as these are not relevant outside Stencil. (Remember, in a headless storefront GraphQL Storefront API requests are proxied.) ### Custom Login Page Most headless storefronts will utilize their own authentication and session management. In addition, the most common approach to the standard BigCommerce GraphQL Storefront API in headless storefronts is to use server-side, stateful requests with a **customer access token** for customer context. In this scenario, these two key steps will provide the necessary **B2B storefront token** to the Buyer Portal: * Use the [B2B REST Management API](/developer/api-reference/rest/b2b/management/authentication/post-auth-customers-storefront) to obtain a B2B storefront token using the BigCommerce customer access token. * Use `window.b2b.utils.loginWithB2BStorefrontToken` to set the token properly in the session and ensure the Buyer Portal hydrates the user's session details. > **Info** > > **In Catalyst** > > The Catalyst integration utilizes the Custom Login Page approach, adding the above steps to the typical authentication flow. ## Resources * [Customer Login API](/developer/docs/storefront/guides/customer-authentication/customer-login) * [Current Customer API](/developer/docs/storefront/guides/customer-authentication/current-customer) * [B2B GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground)