Server to Server Management APIs
Authentication

Authentication

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.

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 (opens in a new tab) in the B2B Edition control panel; however, it is not recommended to use V2 endpoints.

Get a Server to Server Token

POST /auth/backend

Request

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.

Authentication

  • authToken in header

Body

object | application/json
  • storeHash
    string
    required

    The unique store hash for the BigCommerce store.
    >= 1 characters
    Example: 1234abcd
  • password
    string
    required

    The password associated with the user's account.
    >= 1 characters
    Example: MyPassword123
  • name
    string
    required

    The internal name assigned to the generated API token.
    Example: customer storefront token

example

{
"storeHash": "1234abcd",
"email": "user@example.com",
"password": "MyPassword123",
"name": "customer storefront token"
}

Response

OK

Body

object | application/json
  • code
    integer

    The HTTP Status code of the response.

    Default: 200

  • data
    array[object]

  • meta
    object

example

{
"code": 200,
"data": [
{
"name": "customer storefront token",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ.L_u_enljWoYBbPPskmYEQVHldHIaTcWMIB-SdFah850"
}
],
"meta": {
"message": "SUCCESS"
}
}

Delete Backend API Tokens

DELETE /auth/backend

Request

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 endpoint.

Note: Unlike most DELETE requests, the id value must be added to the request body instead of the parameters.

Authentication

  • authToken in header

Body

object | application/json
  • name
    string

    The internal name assigned to the generated API token.
    Example: customer storefront token
  • id
    integer
    required

    The internal ID for the API token.
    Example: 123

example

curl --request DELETE \
--url https://api-b2b.bigcommerce.com/api/v3/io/auth/backend \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    integer

    The HTTP Status code of the response.

    Default: 200

  • data
    array[]

  • meta
    object

example

{
"code": 200,
"data": [],
"meta": {
"message": "SUCCESS"
}
}

Get Storefront authToken with Credentials

POST /auth/customers

Request

Uses the login credentials of a storefront customer or a Company user to generate a storefront authToken to validate requests to the B2B Storefront GraphQL API. Unlike the Get a Storefront API authToken endpoint, this request does not rely on a JWT from an active storefront session.

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.

Authentication

  • authToken in header

Body

object | application/json
  • storeHash
    string
    required

    The unique store hash for the BigCommerce store.
    >= 1 characters
    Example: 1234abcd
  • password
    string
    required

    The password associated with the user's account.
    >= 1 characters
    Example: MyPassword123
  • channelId
    number
    required

    The storefront channel ID associated with the storefront login session. Use 1 for your store’s default storefront channel.
    Example: 1000234

    Default: 1

  • name
    string
    required

    The internal name assigned to the generated API token.
    Example: customer storefront token
  • beginAt
    integer

    The Unix timestamp indicating when the storefront authToken starts being valid.
    Example: 1721900486
  • endAt
    integer

    The Unix timestamp indicating when the storefront authToken is no longer valid.
    Example: 1721900486

example

{
"storeHash": "1234abcd",
"email": "user@example.com",
"password": "MyPassword123",
"channelId": 1000234,
"name": "customer storefront token",
"beginAt": 1721900486,
"endAt": 1721900486
}

Response

OK

Body

object | application/json
  • code
    integer

    The HTTP Status code of the response.

    Default: 200

  • data
    object

  • meta
    object

example

{
"code": 200,
"data": {
"name": "customer storefront token",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ.L_u_enljWoYBbPPskmYEQVHldHIaTcWMIB-SdFah850"
},
"meta": {
"message": "SUCCESS"
}
}

Get a B2B Storefront Token

POST /auth/customers/storefront

Request

Generates a storefront authToken based on the supplied customerId of a storefront customer or Company user. You can use Get Users to retrieve the IDs of Company users, or you can use Get All Customers to retrieve IDs for B2C customers and B2B buyers alike.

You can also use the BigCommerce Storefront GraphQL API to generate a Customer Access Token (CAT) and include it in the request, but this is not required for a successful response.

The storefront authToken obtained from this endpoint is valid for 1 day.

Authentication

  • authToken in header

Body

object | application/json
  • customerId
    integer
    required

    The BigCommerce Customer ID.
    Example: 456
  • channelId
    number

    The storefront channel ID associated with the storefront login session. Use 1 for your store’s default storefront channel.
    Example: 1000234

    Default: 1

  • customerAccessToken
    object

    This object contains information related to the Customer Access Token (CAT) being associated with the storefront authToken.

example

{
"customerId": 456,
"channelId": 1000234,
"customerAccessToken": {
"expires_at": "2024-12-31T00:00:00.0Z",
"value": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ.L_u_enljWoYBbPPskmYEQVHldHIaTcWMIB-SdFah850"
}
}

Response

OK

Body

object | application/json
  • code
    integer

    The HTTP Status code of the response.

    Default: 200

  • data
    object

  • meta
    object

example

{
"code": 200,
"data": {
"token": [
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6IjEyM0AxMi5jb20iLCJiY19jdXN0b21lcl9pZCI6MzEzLCJzdG9yZV9oYXNoIjoiaW1rOHp6N2ppcCIsImRiIjoiZGVmYXVsdCIsImJjX2NoYW5uZWxfaWQiOjEsImV4cCI6MTY5MDg1NDI5Mn0.97rY-1aGDFKtLbIePR5g202AHZJ0x2kDjmyzGVGK45"
]
},
"meta": {
"message": "SUCCESS"
}
}

Get a Storefront API authToken

GET /auth/storefront

Request

Returns an existing storefront authToken from an existing JSON Web Token (JWT). You can obtain a JWT using a request to the Current Customer API. See Authentication for hosted storefronts for instructions.

The channelId field is optional for stores with multiple storefronts, since the JWT is tied to a specific storefront session. Including it does enforce strict adherence of token-related activity to channel-specific rules and behaviors. However, it is not necessary at all for single-storefront stores because there is only one storefront channel.

The storefront authToken obtained from this endpoint is valid for 1 day.

Authentication

  • authToken in header

Parameters

  • jwtToken in query - string
    required
    The JSON Web Token (JWT) obtained from a signed-in Company user. See Current Customer API to learn how to request a JWT.
  • channelId in query - string

    The storefront channel ID associated with the storefront login session. Use 1 for your store’s default storefront channel. In a multi-storefront environment, this parameter enforces strict adherence of token-related activity to channel-specific rules and behaviors.

    Note: Inclusion of this parameter in single-storefront environments will result in unpredictable behavior.

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/auth/storefront \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    integer

    The HTTP Status code of the response.

    Default: 200

  • data
    object

  • meta
    object

example

{
"code": 200,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ.L_u_enljWoYBbPPskmYEQVHldHIaTcWMIB-SdFah850"
},
"meta": {
"message": "SUCCESS"
}
}

Get All Server to Server Tokens

GET /backend/tokens

Request

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.

Authentication

  • authToken in header

Parameters

  • limit in query with default of 10 - integer
    The maximum number of results that can be in the response.
  • offset in query0 - integer
    The number of results that should be skipped in the response.

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/backend/tokens \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json
  • code
    integer

    The HTTP Status code of the response.

    Default: 200

  • data
    array[object]

  • meta
    object

example

{
"code": 200,
"data": [
{
"id": 123,
"name": "customer storefront token",
"email": "user@example.com",
"storeHash": "1234abcd",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ.L_u_enljWoYBbPPskmYEQVHldHIaTcWMIB-SdFah850",
"eventChannel": "app"
}
],
"meta": {
"message": "SUCCESS",
"pagination": {
"totalCount": 25,
"limit": 10,
"offset": 0
}
}
}

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?