> 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 for hosted storefronts > **Note** > > As of September 30, 2025, the B2B Edition API `authToken` is deprecated and replaced by the standard BigCommerce API `X-Auth-Token` used together with a new header `X-Store-Hash`. This change only applies to Server-to-Server requests. Storefront requests remain unchanged. > > While `authToken` authentication is not expected to be fully sunset in the near future, it is advised to migrate to the new system as soon as possible to prevent disruption of functionality. > > The server and path for B2B REST Management API endpoints remains the same. Authentication provides vital security for your application by verifying who can access certain data. B2B Edition provides several methods for retrieving tokens that can be used to authenticate requests to server to server and storefront APIs. ## Server-to-Server Tokens BigCommerce API authentication tokens are used to authenticate requests to the B2B REST Management API. These tokens use specially managed scopes for B2B Edition and are configured ahead via the BigCommerce control panel. ### Creating an API Account Creating an API Account is recommended for backend users who need access to relevant account features, company management, and other tasks available through the B2B REST Management API. The process for setting up a store-level token is dependent on the appropriate BigCommerce permissions being enabled. Specifically, only users with the `Create store-level API Accounts` permission enabled can set up the necessary token. To create a token for server-to-server requests, 1. Navigate to `Settings > Store-level API accounts` in the BigCommerce Control Panel. 2. Click Create API Account. 3. Create a V3 Token with the B2B Edition scope set to `modify`. 4. Save the relevant account keys for future reference. > **Note** > > If you are a partner building an app intended for use with B2B Edition, you will need to ensure the B2B Edition scope is enabled before publishing the app. For more information on creating and managing API accounts, refer to [API Accounts (Help Center)](https://support.bigcommerce.com/s/article/Store-API-Accounts). > **Note** > > If your store doesn't have B2B Edition enabled, the B2B Edition scope will not be available. Reach out to support or sales to enable B2B Edition. ### Using the REST Management API When using the B2B REST Management API, two header parameters are required for authentication: access token and store hash. Both are returned in the API account creation process. Specifically, your requests should include the headers * `X-Auth-Token` - The ACCESS TOKEN provided during API account creation. This is required for authentication across all server-to-server endpoints. * `X-Store-Hash` - The STORE HASH provided during API account creation. This hash is unique to the store, but not to the account. This ensures requests are made to the appropriate B2B Edition account. > **Note** > > An `X-Auth-Token` used without an `X-Store-Hash` or with a mismatched hash will return server errors. Ensure both are correct before making calls to the API. The `X-Auth-Token` structure is designed for long-term use. As such, they do not expire by default. User-specific tokens can be generated by the **deprecated** [Get a Server to Server Token](/developer/api-reference/rest/b2b/management/authentication/post-auth-backend) endpoint. Rather than relying on an existing token, it generates an `authToken` by validating a backend user's login credentials and the store hash. Server to server tokens can be configured to expire using this endpoint to set a fixed validity period using the `endAt` field in the request. For more information, see [Server-to-Server Authentication](/developer/docs/b2b-edition/getting-started/authentication). > **Note** > > This endpoint generates an `authToken`, which is deprecated. In addition, it does not support users with custom system user roles, even if those roles have API account creation permissions. > **Note** > > If you are still using the B2B Edition specific `authToken`, the store hash is not needed as the token includes that information. Including `X-Store-Hash` with `authToken` will have unexpected results. Please migrate to the unified token structure as soon as possible to avoid loss of functionality. **`Fetch request example`** ```js title="Fetch request example" showLineNumbers={false} async function() { try { let authToken = await fetch({ method: "post", url: "https://api-b2b.bigcommerce.com/api/v3/io/auth/backend", body: { storeHash: "", email: "", password: "", channelId: 1, name: "optionalTokenName", beginAt: 1000, endAt: 17219304, // Unix timestamp for expiry } }); return authToken; } catch(error) { console.log(error); throw error; } } ``` Tokens created via API can be invalidated as necessary using the **deprecated** [Delete Backend API Tokens](/developer/api-reference/rest/b2b/management/authentication/delete-auth-backend) endpoint. ## Storefront Tokens > **Note** > > **Note:** This section covers authentication for the B2B Edition GraphQL Storefront API. It is best practice to use GraphQL mutations when generating storefront authTokens on B2B Edition's Buyer Portal experience. For information about the equivalent REST Storefront Authentication API requests, see [Authentication](/developer/docs/b2b-edition/getting-started/authentication). B2B Edition's REST Storefront and GraphQL Storefront APIs allow you to query and modify data from the context of a storefront user. Depending on your store's configurations, you can perform certain actions as a guest shopper, a B2C customer with a storefront account, a B2B buyer with a Company user account, or a [Super Admin](/developer/api-reference/rest/b2b/management/super-admin) user. Certain requests are considered *anonymous* and do not require a storefront authToken for validation. This includes requests that can be performed as a guest shopper without an account, such as the [companyCreate](/developer/api-reference/rest/b2b/storefront/company/companies/createcompany-frontend) mutation, as well as mutations that generate tokens themselves. To view or modify data from the context of a storefront user with an account, you must authenticate it by including a storefront authToken passed with the `Authorization` header. Storefront authTokens have the following differences from server to server authToken: * They are bearer tokens tied to a specific user. * They automatically expire after **1 day**. Refresh a storefront authToken with a new request. * A storefront authToken's scope depends on the corresponding user. * For example, a token generated for a B2C customer authenticates any request that does not require a Company account, while one for a B2B buyer can only authenticate a request if the buyer's Company user account has the corresponding [permissions](/developer/api-reference/rest/b2b/management/company/company-roles-and-permissions/get-stores-companies-permissions) enabled. The [BigCommerce GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api/authentication) requires different authentication tokens for client- and server-side contexts. With the B2B GraphQL API, authentication tokens are always in the context of a specific user, and they do not rely on storefront cookies. The sections below provide information about the different methods for generating a storefront authToken. All methods can be used in both Stencil and headless storefronts. ### The *login* Mutation The `login` mutation allows you to gather an authToken with the credentials used by Company users to log in to the Buyer Portal. This request is performed independently of a standard customer session in the storefront, but you can sync their login by including the `storefrontLoginToken` field in the request. The `storefrontLoginToken` field returns a JSON Web Token (JWT) signed with the B2B Edition client secret. To sync the login with a storefront session, pass the JWT to the [Customer Login](/developer/docs/storefront/guides/customer-authentication/customer-login) endpoint. The examples below include the request body and variables for generating a storefront authToken and JWT with user details, as well as the expected response. **`Example login request`** ```graphql title="Example login request" showLineNumbers={false} mutation LogIn( $storeHash: String!, $email: String!, $password: String! ) { login( loginData: { storeHash: $storeHash, email: $email, password: $password } ) { result { token storefrontLoginToken user { id bcId firstName lastName email } } } } ``` **`Variables`** ```graphql title="Variables" showLineNumbers={false} { "storeHash": "{The BigCommerce store hash}", "email": "{The Company user email address}", "password": "{The Company user password}" } ``` **`Example login response`** ```json title="Example login response" showLineNumbers={false} { "data": { "login": { "result": { "token": "{storefront authToken)", "storefrontLoginToken": "{JWT}", "user": { "id": "12345", "bcId": 123, "firstName": "Marie", "lastName": "Curie", "email": "mcurie@greatbuysinc.com" } } } } } ``` To learn more about the `login` mutation, see our [storefront authentication](/developer/api-reference/rest/b2b/storefront/authentication/post-auth-customer) documentation. ### The *authorization* Mutation If you want your integration to use an existing storefront session for a logged-in Company user to generate a storefront authToken, you can accomplish this with the `authorization` mutation. The request uses a JWT to retrieve a token that can be used to authenticate further requests to the GraphQL API while the user is logged in. To obtain a JWT for validation, make a request to the BigCommerce [Current Customer API](/developer/api-reference/rest/admin/authentication-apis/current-customer/overview) while passing the B2B Edition client ID (`dl7c39mdpul6hyc489yk0vzxl6jesyx`) with the `app-client-id` query parameter. Here's an example of a Fetch request that you can use to obtain a JWT for B2B Edition. Replace the example domain in the endpoint with your store's domain. **`Fetch request example`** ```js title="Fetch request example" showLineNumbers={false} const options = { method: 'GET', headers: {Accept: 'application/json', 'Content-Type': 'application/json'} }; fetch('https://mybcstore.com/customer/current.jwt?app_client_id=dl7c39mdpul6hyc489yk0vzxl6jesyx', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` You can pass the resulting JWT to the `authorization` mutation without decoding it. The request can be structured as follows: **`Example authorization request`** ```graphql title="Example authorization request" showLineNumbers={false} mutation userAuth( $bcToken: String!, $channelId: Int! ) { authorization( authData: { bcToken: $bcToken, channelId: $channelId } ) { result { token } } } ``` **`Variables`** ```graphql title="Variables" showLineNumbers={false} { "bcToken": "{The JWT for the storefront session}", "channelId": {BigCommerce storefront channel ID; use 1 for the default channel} } ``` **`Example authorization response`** ```json title="Example authorization response" showLineNumbers={false} { "data": { "authorization": { "result": { "token": "{storefront authToken}" } } } } ``` See our article on [storefront authentication](/developer/api-reference/rest/b2b/storefront/authentication/post-login) to learn more about this mutation's usage and fields. ### REST Management API Endpoints If your integration or headless solution is built to use server-side endpoints, you can also retrieve storefront authTokens via B2B Edition's REST Management Authentication API. Each endpoint uses a server to server authToken for validation, but they also require specific fields or parameters based on their use case. | Request | Description | Use case | | :-------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | | [Get Storefront authToken with Credentials](#get-storefront-authtoken-with-credentials) | Uses a Company user's login email and password to generate a token | Authenticating requests after a Company user logs in | | [Get a B2B Storefront Token](#get-a-b2b-storefront-token) | Generates a token based on the supplied `customerId` of a Company user | Syncing a token with an authentication already performed with BigCommerce's GraphQL Storefront API | | [Get a Storefront API authToken](#get-a-storefront-api-authtoken) | Returns an existing token based on its corresponding JWT | Syncing a token with an active storefront session | #### Get Storefront authToken with Credentials Like the [login mutation](#the-login-mutation), this endpoint validates a Company user's login credentials to create a storefront authToken for future requests. The resulting token has the default validity period of 1 day, but you can use the `beginAt` and `endAt` fields in the request body to specify a custom period. See our [server to server authentication](/developer/docs/b2b-edition/getting-started/authentication#get-storefront-authtoken-with-credentials) documentation for information on formatting the request. #### Get a B2B Storefront Token The [Get a B2B Storefront Token](/developer/docs/b2b-edition/getting-started/authentication#get-a-b2b-storefront-token) endpoint only requires a customer ID to retrieve a storefront authToken. However, this token does not automatically sync with a storefront session. To sync a login with the token, you must include a customer access token (CAT) in the request body. You can retrieve a CAT by using the `login` mutation of the [BigCommerce GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api/customer-context#login-mutation), **not** the [equivalent request](#the-login-mutation) in the B2B Edition GraphQL Storefront API. #### Get a Storefront API authToken Rather than targeting a specific Company user, this endpoint retrieves an existing storefront authToken based on the JWT associated with an active storefront session. As with the [authorization mutation](#the-authorization-mutation), you can use the [Current Customer API](/developer/docs/storefront/guides/customer-authentication/current-customer) to retrieve a JWT and pass it to the `jwtToken` query parameter of the request. Here are two examples of how you can format the request: **`CURL request example`** ```curl title="CURL request example" showLineNumbers={false} curl https://api-b2b.bigcommerce.com/api/io/auth/storefront?jwtToken=bigCommerce.currentCustomerResponse.jwtString&channelId=1 ``` **`Fetch request example`** ```js title="Fetch request example" showLineNumbers={false} async function() { try { let authToken = await fetch({ method: "get", url: "https://api-b2b.bigcommerce.com/api/io/auth/storefront", query:{ jwtToken: "bigCommerce.currentCustomerResponse.jwtString", channelId: 1 } }); return authToken; } catch(error) { console.log(error); throw error; } } ``` ## Resources * [Authentication](/developer/docs/b2b-edition/getting-started/authentication) (Server to Server) * [Authentication](/developer/docs/b2b-edition/getting-started/authentication) (Storefront) * [Current Customer](/developer/docs/storefront/guides/customer-authentication/current-customer) * [Authenticating requests to the GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api/authentication)