diff --git a/docs/b2b-edition/authentication/hosted-auth.mdx b/docs/b2b-edition/authentication/hosted-auth.mdx index 5d7855dc2..7e8bdc56d 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`. 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. + +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 **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). - 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() { @@ -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 @@ -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) - 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: |-