Skip to content

DEVDOCS-6568 - Revise B2B authentication #1130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 31, 2025
Merged

DEVDOCS-6568 - Revise B2B authentication #1130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2477917
DEVDOCS-6568 - Revise B2B authentication
bc-terra Oct 24, 2025
9e39ce8
Revise authentication YAML for clarity and deprecation
bc-terra Oct 24, 2025
e039a5e
Apply suggestion from @bc-terra
bc-terra Oct 24, 2025
b0056d6
Mark Delete Backend API Tokens endpoint as deprecated
bc-terra Oct 24, 2025
8a78b18
Update docs/b2b-edition/authentication/hosted-auth.mdx
bc-terra Oct 31, 2025
d8eb4aa
Merge branch 'main' into DEVDOCS-6568
bc-terra Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 18 additions & 6 deletions docs/b2b-edition/authentication/hosted-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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">
Expand All @@ -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 **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() {
Expand All @@ -77,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

Expand Down Expand Up @@ -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)

Loading