Merge branch 'main' into DEVDOCS-6340

Author: chris-nowicki

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
 
 <Callout type="important">
-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`. 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.
 
@@ -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.
 
+<Callout type="info">
+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.
+</Callout>
+
 For more information on creating and managing API accounts, refer to [API Accounts (Help Center)](https://support.bigcommerce.com/s/article/Store-API-Accounts).
 
 <Callout type="warning">
@@ -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-server-to-server-tokens) endpoint, which generates a server-to-server token by validating a backend user’s login credentials and the store hash instead of relying on an existing token. 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 **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).
 
 <Callout type= "warning">
-   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.
 </Callout> 
 
-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]
+<Callout type="info">
+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.
+</Callout>
 
 ```js filename="Fetch request example" copy
 async function() {
@@ -77,14 +90,12 @@ 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.
-
-For more details, see the [B2B Edition Settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings).
+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
 
 <Callout type= "info">
-   **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](/b2b-edition/apis/rest-storefront/sales-rep).
+   **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](/b2b-edition/apis/rest-storefront/authentication).
 </Callout>
 
 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](/b2b-edition/apis/rest-storefront/sales-rep) user.
@@ -183,7 +194,7 @@ const options = {
   headers: {Accept: 'application/json', 'Content-Type': 'application/json'}
 };
 
-fetch('https://mybcstore.com/customer/current.jwt?$app_client_id=dl7c39mdpul6hyc489yk0vzxl6jesyx', options)
+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));
@@ -230,7 +241,7 @@ mutation userAuth(
 
 See our article on [storefront authentication](/b2b-edition/apis/rest-storefront/authentication#get-storefront-authtoken-within-stencil) to learn more about this mutation’s usage and fields.
 
-### Rest Management API Endpoints
+### 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.  
 
@@ -288,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)
-

docs/b2b-edition/specs/api-v3/address/address.yaml

@@ -22,10 +22,9 @@ tags:
   - name: Addresses
 security:
   - X-Auth-Token: []
+    X-Store-Hash: []
 paths:
   /countries:
-    parameters:
-      - $ref: "#/components/parameters/X-Store-Hash"
     get:
       summary: Get a Country
       tags:
@@ -121,8 +120,6 @@ paths:
                     meta:
                       message: Resource not found
   /states:
-    parameters:
-      - $ref: "#/components/parameters/X-Store-Hash"
     get:
       summary: Get a State
       tags:
@@ -395,8 +392,6 @@ paths:
                   - code
                   - data
                   - meta
-    parameters:
-      - $ref: "#/components/parameters/X-Store-Hash"
     post:
       summary: Create a Company Address
       operationId: post-companies-companyId-addresses
@@ -515,7 +510,6 @@ paths:
                       message: "Parameter Error"
   '/addresses/{addressId}':
     parameters:
-      - $ref: "#/components/parameters/X-Store-Hash"
       - schema:
           type: string
         name: addressId
@@ -652,8 +646,6 @@ paths:
               schema:
                 $ref: '#/components/schemas/responseNotFound'
   /addresses/bulk:
-    parameters:
-      - $ref: "#/components/parameters/X-Store-Hash"
     post:
       summary: Bulk Create Addresses
       operationId: post-addresses
@@ -887,8 +879,6 @@ paths:
                     meta:
                       message: "Parameter Error"
   /addresses/extra-fields:
-    parameters:
-      - $ref: "#/components/parameters/X-Store-Hash"
     get:
       summary: Get Address Extra Field Configs
       tags:
@@ -988,14 +978,6 @@ paths:
                   - meta
 components:
   parameters:
-    X-Store-Hash:
-      name: X-Store-Hash
-      in: header
-      required: true
-      schema:
-        type: string
-        example: abc123
-      description: The unique store hash associated with a BigCommerce store that has B2B Edition enabled.
     limit:
       name: limit
       in: query
@@ -1305,6 +1287,16 @@ components:
         - data
         - meta
   securitySchemes:
+    X-Store-Hash:
+      name: X-Store-Hash
+      description: |-
+        ### Authentication header
+
+        | Header | Argument | Description |
+        |:-------|:---------|:------------|
+        | `X-Store-Hash` | `store_hash` | The unique store hash associated with a BigCommerce store that has B2B Edition enabled. |
+      type: apiKey
+      in: header
     X-Auth-Token:
       name: X-Auth-Token
       description: |-