From 2477917910b7681b04fe6ace2630b9e8031e4a23 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 24 Oct 2025 08:29:41 -0600 Subject: [PATCH 1/5] DEVDOCS-6568 - Revise B2B authentication Updated the hosted authentication documentation to clarify the deprecation of `authToken` and the introduction of `X-Auth-Token` and `X-Store-Hash`. Adjusted information about token generation and invalidation. --- .../authentication/hosted-auth.mdx | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/b2b-edition/authentication/hosted-auth.mdx b/docs/b2b-edition/authentication/hosted-auth.mdx index 5d7855dc2..2752d37be 100644 --- a/docs/b2b-edition/authentication/hosted-auth.mdx +++ b/docs/b2b-edition/authentication/hosted-auth.mdx @@ -1,7 +1,12 @@ +--- +title: Authentication for hosted storefronts +keywords: b2b edition, authentication, api token +--- + # Authentication for hosted storefronts -As of September 30, 2025, the B2B Edition API `authToken` will be deprecated and replaced by the standard BigCommerce API `X-Auth-Token`. +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`. 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. @@ -26,6 +31,10 @@ To create a token for server-to-server requests, 3. Create a V3 Token with the B2B Edition scope set to `modify`. 4. Save the relevant account keys for future reference. + +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). @@ -45,13 +54,17 @@ An `X-Auth-Token` used without an `X-Store-Hash` or with a mismatched hash will 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 [Get a Server to Server Token](/b2b-edition/apis/rest-management/authentication#get-a-server-to-server-token) endpoint. Rather than relying on an existing token, it generates a server-to-server token by validating a backend user’s login credentials and the store hash. This is useful if you are building an integration which automatically generates a token for Store Owner or Administrator users. +User-specific tokens can be generated by the [Get a Server to Server Token](/b2b-edition/apis/rest-management/authentication#get-a-server-to-server-token) 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](/b2b-edition/apis/rest-management/authentication). - This endpoint does not support users with custom system user roles, even if those roles have API account creation permissions. + 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. -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](/b2b-edition/apis/rest-management/authentication). + +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. + ```js filename="Fetch request example" copy async function() { @@ -286,4 +299,3 @@ async function() { * [Authentication](/b2b-edition/apis/rest-storefront/authentication) (Storefront) * [Current Customer](/docs/storefront-auth/current-customer) * [Authenticating requests to the GraphQL Storefront API](/docs/start/authentication/graphql-storefront) - From 9e39ce829834ccdefad03b494f6e5d1a71e1cd49 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 24 Oct 2025 09:06:32 -0600 Subject: [PATCH 2/5] Revise authentication YAML for clarity and deprecation Updated authentication documentation to clarify token usage and deprecated endpoints. --- .../specs/api-v3/authentication.yaml | 358 +++++++++--------- 1 file changed, 185 insertions(+), 173 deletions(-) diff --git a/docs/b2b-edition/specs/api-v3/authentication.yaml b/docs/b2b-edition/specs/api-v3/authentication.yaml index 5bb2639dd..08aea324f 100644 --- a/docs/b2b-edition/specs/api-v3/authentication.yaml +++ b/docs/b2b-edition/specs/api-v3/authentication.yaml @@ -9,16 +9,16 @@ info: > 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. ## Introduction - Authentication tokens validate API requests made by individuals or integrations to the server. All Server to Server API requests require an `authToken` in the header of the request. + Authentication tokens validate API requests made by individuals or integrations to the server. All Server to Server API requests require an API token in the header of the request. When using the `X-Auth-Token` header with B2B Edition Server to Server API requests, the `X-Store-Hash` header is also required. + + See [B2B Authentication](/b2b-edition/docs/authentication) for information on how to generate BigCommerce API tokens with appropriate scopes to use the B2B Edition Server to Server API. Using authentication endpoints, you can: - - Create Server to Server API tokens outside of the B2B Edition control panel. - - View and delete existing API tokens. - Arrange for your integration to log in a storefront user and gather tokens for future GraphQL requests in the context of a particular Company and user. - Validate a storefront user’s credentials in order to generate a GQL token. - The Authentication API allows you to create V3 Server to Server and storefront authTokens, but you cannot create tokens for the deprecated V2 Server to Server API. You can create V2 tokens using the [API Account settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the B2B Edition control panel; however, it is not recommended to use V2 endpoints. + The Authentication API allows you to create only storefront authTokens and deprecated V3 Server to Server authTokens, but you cannot create tokens for the deprecated V2 Server to Server API. You can create V2 tokens using the [API Account settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) in the B2B Edition control panel; however, it is not recommended to use V2 endpoints. contact: name: BigCommerce url: 'https://www.bigcommerce.com' @@ -32,168 +32,8 @@ tags: - name: Authentication paths: - /auth/backend: - parameters: - - $ref: "#/components/parameters/X-Store-Hash" - post: - tags: - - Authentication - summary: "Get a Server to Server Token" - operationId: post-auth-backend - description: |- - Creates a Server to Server API account with a token to validate future requests made to B2B’s Server to Server APIs. - - This endpoint does not require an existing authToken, but you must validate the request with the login credentials of your backend B2B Edition user account. Only users with the pre-built Administrator or Store Owner role are allowed to create API tokens with this endpoint; custom user roles with API account permissions are **not** supported. - parameters: [] - security: [] - requestBody: - content: - application/json: - schema: - type: object - required: - - storeHash - - email - - password - - name - properties: - storeHash: - $ref: "#/components/schemas/storeHash" - email: - $ref: "#/components/schemas/email" - password: - $ref: "#/components/schemas/password" - name: - $ref: "#/components/schemas/tokenName" - responses: - "200": - description: OK - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/responseArray" - - type: object - properties: - code: - default: 200 - data: - items: - type: object - properties: - name: - $ref: "#/components/schemas/tokenName" - token: - allOf: - - $ref: "#/components/schemas/tokenValue" - - description: "The token value used to authenticate requests." - meta: - properties: - message: - example: "SUCCESS" - "400": - description: BAD REQUEST - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/responseObject" - - type: object - properties: - code: - default: 400 - data: - properties: - errMsg: - allOf: - - $ref: "#/components/schemas/errMsg" - - type: string - example: "The email or password you have entered is incorrect. Please try again." - meta: - properties: - message: - example: "API logic error" - examples: - Invalid login credentials: - value: - code: 400 - data: - errMsg: "The email or password you have entered is incorrect. Please try again." - meta: - message: "API logic error" - Unsupported user role: - value: - code: 400 - data: - errMsg: "role forbidden" - meta: - message: "API logic error" - delete: - tags: - - Authentication - summary: "Delete Backend API Tokens" - operationId: delete-auth-backend - description: |- - Deletes an existing Server to Server API token by specifying its ID. You can get a token’s ID using the [Get All Server to Server Tokens](#get-all-server-to-server-tokens) endpoint. - - **Note:** Unlike most DELETE requests, the `id` value must be added to the request body instead of the parameters. - parameters: [] - security: [] - requestBody: - content: - application/json: - schema: - type: object - required: - - id - properties: - email: - $ref: "#/components/schemas/email" - name: - $ref: "#/components/schemas/tokenName" - id: - $ref: "#/components/schemas/tokenId" - responses: - "200": - description: OK - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/responseArray" - - type: object - properties: - code: - default: 200 - meta: - properties: - message: - example: "SUCCESS" - "404": - description: NOT FOUND - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/responseObject" - - type: object - properties: - code: - default: 404 - data: - properties: - errMsg: - allOf: - - $ref: "#/components/schemas/errMsg" - - type: string - example: "No matching token was found." - meta: - properties: - message: - example: "Not Found Error" /auth/customers: - parameters: - - $ref: "#/components/parameters/X-Store-Hash" + parameters: [] post: tags: - Authentication @@ -204,7 +44,6 @@ paths: By default, the resulting storefront authToken is valid for **1 day**. However, you can adjust its validity period with the `beginAt` and `endAt` fields in the request body. parameters: [] - security: [] requestBody: content: application/json: @@ -260,8 +99,7 @@ paths: message: example: "SUCCESS" /auth/customers/storefront: - parameters: - - $ref: "#/components/parameters/X-Store-Hash" + parameters: [] post: tags: - Authentication @@ -274,7 +112,6 @@ paths: The storefront authToken obtained from this endpoint is valid for **1 day**. parameters: [] - security: [] requestBody: content: application/json: @@ -389,15 +226,184 @@ paths: properties: message: example: "Invalid token header. No credentials provided." + /auth/backend: + parameters: [] + post: + deprecated: true + tags: + - Authentication + summary: "Get a Server to Server Token" + operationId: post-auth-backend + description: |- + Creates a Server to Server API account with a token to validate future requests made to B2B’s Server to Server APIs. + + This endpoint does not require an existing API Account, but you must validate the request with the login credentials of your backend B2B Edition user account. Only users with the pre-built Administrator or Store Owner role are allowed to create API tokens with this endpoint; custom user roles with API account permissions are **not** supported. + + > NOTE + > + > This endpoint generates `authToken` API Accounts, which are considered deprecated as of September 30, 2025. It is recommended to use the BigCommerce API `X-Auth-Token` created in the control panel moving forward. + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - storeHash + - email + - password + - name + properties: + storeHash: + $ref: "#/components/schemas/storeHash" + email: + $ref: "#/components/schemas/email" + password: + $ref: "#/components/schemas/password" + name: + $ref: "#/components/schemas/tokenName" + responses: + "200": + description: OK + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/responseArray" + - type: object + properties: + code: + default: 200 + data: + items: + type: object + properties: + name: + $ref: "#/components/schemas/tokenName" + token: + allOf: + - $ref: "#/components/schemas/tokenValue" + - description: "The token value used to authenticate requests." + meta: + properties: + message: + example: "SUCCESS" + "400": + description: BAD REQUEST + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/responseObject" + - type: object + properties: + code: + default: 400 + data: + properties: + errMsg: + allOf: + - $ref: "#/components/schemas/errMsg" + - type: string + example: "The email or password you have entered is incorrect. Please try again." + meta: + properties: + message: + example: "API logic error" + examples: + Invalid login credentials: + value: + code: 400 + data: + errMsg: "The email or password you have entered is incorrect. Please try again." + meta: + message: "API logic error" + Unsupported user role: + value: + code: 400 + data: + errMsg: "role forbidden" + meta: + message: "API logic error" + delete: + deprecated: true + tags: + - Authentication + summary: "Delete Backend API Tokens" + operationId: delete-auth-backend + description: |- + Deletes an existing Server to Server API `authToken` by specifying its ID. You can get a token’s ID using the [Get All Server to Server Tokens](#get-all-server-to-server-tokens) endpoint. This endpoint cannot be used to delete a BigCommerce API `X-Auth-Token`. + + **Note:** Unlike most DELETE requests, the `id` value must be added to the request body instead of the parameters. + parameters: [] + security: + - authToken: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - id + properties: + email: + $ref: "#/components/schemas/email" + name: + $ref: "#/components/schemas/tokenName" + id: + $ref: "#/components/schemas/tokenId" + responses: + "200": + description: OK + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/responseArray" + - type: object + properties: + code: + default: 200 + meta: + properties: + message: + example: "SUCCESS" + "404": + description: NOT FOUND + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/responseObject" + - type: object + properties: + code: + default: 404 + data: + properties: + errMsg: + allOf: + - $ref: "#/components/schemas/errMsg" + - type: string + example: "No matching token was found." + meta: + properties: + message: + example: "Not Found Error" /backend/tokens: - parameters: - - $ref: "#/components/parameters/X-Store-Hash" + parameters: [] get: + deprecated: true tags: - Authentication summary: "Get All Server to Server Tokens" operationId: get-backend-tokens - description: "Retrieves all B2B S2S API tokens associated with your store. You can use the token’s ID in the response to delete it via the Delete Backend API Tokens endpoint, or you can recover existing token values for further Server to Server requests." + description: |- + > NOTE + > + > This endpoint only retrieves `authToken` and not `X-Auth-Token` information. + + Retrieves all B2B S2S API tokens associated with your store. You can use the token’s ID in the response to delete it via the Delete Backend API Tokens endpoint, or you can recover existing token values for further Server to Server requests. parameters: - name: limit in: query @@ -416,7 +422,8 @@ paths: minimum: 0 description: "The number of results that should be skipped in the response." example: 10 - security: [] + security: + - authToken: [] responses: "200": description: OK @@ -570,6 +577,11 @@ components: type: string securitySchemes: + authToken: + name: authToken + description: Required to authenticate requests. Include the token in a header parameter called `authToken`. + type: apiKey + in: header X-Auth-Token: name: X-Auth-Token description: |- From e039a5e15c1795469248f96b79ce1b21af854d27 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 24 Oct 2025 09:07:59 -0600 Subject: [PATCH 3/5] Apply suggestion from @bc-terra --- docs/b2b-edition/authentication/hosted-auth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/b2b-edition/authentication/hosted-auth.mdx b/docs/b2b-edition/authentication/hosted-auth.mdx index 2752d37be..37b98ddf7 100644 --- a/docs/b2b-edition/authentication/hosted-auth.mdx +++ b/docs/b2b-edition/authentication/hosted-auth.mdx @@ -54,7 +54,7 @@ An `X-Auth-Token` used without an `X-Store-Hash` or with a mismatched hash will 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 [Get a Server to Server Token](/b2b-edition/apis/rest-management/authentication#get-a-server-to-server-token) endpoint. Rather than relying on an existing token, it generates an `authToken` by validating a backend user’s login credentials and the store hash. +User-specific tokens can be generated by the **deprecated** [Get a Server to Server Token](/b2b-edition/apis/rest-management/authentication#get-a-server-to-server-token) 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](/b2b-edition/apis/rest-management/authentication). From b0056d6592287122c46fdbf16990b3518f7814e6 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 24 Oct 2025 09:08:57 -0600 Subject: [PATCH 4/5] Mark Delete Backend API Tokens endpoint as deprecated --- docs/b2b-edition/authentication/hosted-auth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/b2b-edition/authentication/hosted-auth.mdx b/docs/b2b-edition/authentication/hosted-auth.mdx index 37b98ddf7..946d99f14 100644 --- a/docs/b2b-edition/authentication/hosted-auth.mdx +++ b/docs/b2b-edition/authentication/hosted-auth.mdx @@ -90,7 +90,7 @@ async function() { } ``` -Tokens created via API can be invalidated as necessary using the [Delete Backend API Tokens](/b2b-edition/apis/rest-management/authentication#delete-backend-api-tokens) endpoint. +Tokens created via API can be invalidated as necessary using the **deprecated** [Delete Backend API Tokens](/b2b-edition/apis/rest-management/authentication#delete-backend-api-tokens) endpoint. ## Storefront Tokens From 8a78b18d7d3a4f60eedccdd09bc2a2df57c8b3f0 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 31 Oct 2025 07:23:21 -0600 Subject: [PATCH 5/5] Update docs/b2b-edition/authentication/hosted-auth.mdx --- docs/b2b-edition/authentication/hosted-auth.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/b2b-edition/authentication/hosted-auth.mdx b/docs/b2b-edition/authentication/hosted-auth.mdx index 946d99f14..7e8bdc56d 100644 --- a/docs/b2b-edition/authentication/hosted-auth.mdx +++ b/docs/b2b-edition/authentication/hosted-auth.mdx @@ -6,7 +6,7 @@ keywords: b2b edition, authentication, api token # Authentication for hosted storefronts -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`. +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.