B2B Edition
B2B Edition APIs
Storefront APIs
Authentication

Authentication

Introduction

Requests to the B2B Edition Storefront API are either anonymous or authenticated, depending on whether or not it requires access to a Company user’s data.

For example, you can create a Company account (opens in a new tab) anonymously because the action can be performed by a shopper without a user account, but creating a Shopping List (opens in a new tab) must be authenticated since the action is tied to a particular Company account and user.

The B2B Edition Storefront API includes endpoints to generate an authToken with or without specifying an existing Company user. Use the appropriate endpoint to authenticate your requests to Storefront REST APIs and StorefrontGraphQL APIs. Note that storefront authTokens expire after 1 day.

The BigCommerce GraphQL Storefront API (opens in a new tab) requires different authentication tokens for client- and server-side contexts. With the B2B GraphQL API, authentication tokens are always in the context of a specific user, and they don’t rely on storefront cookies.

As a result, these can be used in a client-side and server-side context. This means that you don’t have to change your authentication strategy for requests from the client or a server.

While the Storefront authentication endpoints can be used in either experience, it is best practice to get storefront authTokens via the GraphQL login and authorization mutations if you are developing on the Buyer Portal experience.

The legacy Stencil storefront experience is built to use Storefront endpoints instead of GraphQL mutations, but it can also use GraphQL for authentication-based customizations. For more information on GraphQL structure and usage, see the GraphQL Playground (opens in a new tab).

Get Storefront authToken within Stencil

POST /v2/login

Request

Uses a JSON web token (JWT) from a particular customer or Company user who is currently logged in to the storefront to create a storefront authToken for future requests.

To learn more about how you can retrieve a JWT to create a storefront authToken. See Authentication for hosted storefronts.

Equivalent Storefront GraphQL API Mutation: authorization.

Example GraphQL API Body

mutation {
  authorization(
    authData: {
      bcToken: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY",
      channelId: 1
    }
  ) {
    result {
      token
    }
  }
}

Example GraphQL API Response

{
  "data": {
    "authorization": {
      "result": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY"
      }
    }
  }
}

Body

object | application/json

  • bcToken    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.
    Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY

  • storeHash    string

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

  • 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

  • customerId    integer

    The BigCommerce customer ID associated with a Company user.
    Example: 1234

example

{
"bcToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY",
"storeHash": "1234abcd",
"channelId": 1000234,
"customerId": 1234
}

Response

OK

Body

object | application/json

  • code    number

    Default: 200

  • data    object

  • message    string

    Example: SUCCESS

example

{
"code": 200,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY"
},
"message": "SUCCESS"
}

Get a Storefront authToken for a Specific Customer

POST /io/auth/customers

Request

Validates a Company user’s login credentials to create a storefront authToken that can be queried for future GraphQL requests.

Equivalent Storefront GraphQL API Mutation: login

The GraphQL API mutation also allows you to return a storefrontLoginToken. This retrieves a JWT, which can be passed to the BigCommerce Customer Login endpoint in order to log a customer in with a Stencil storefront session.

The login response also includes information related to the Company user, such as their name and their account’s internal identifiers.

Note: the resulting storefront authToken is tied to the Company user, and their assigned user role determines whether or not further requests are authorized. For example, if you generate an authToken for a user who does not have the create_address permission enabled, using the token to validate the GraphQL API addressCreate mutation will result in an error.

For a complete list of Company user permissions and their scopes, see Company Roles and Permissions.

Example GraphQL API Body

With Storefront authToken only

mutation {
  login(
    loginData: {
      storeHash: "1234abcd",
      email: "axe@snapmail.cc",
      password: "MyPassword123"
    }
  ) {
    result {
      token
      user {
        id
        bcId
        firstName
        lastName
        email
      }
    }
  }
}

With Storefront authToken and storefrontLoginToken

mutation {
  login(
    loginData: {
      storeHash: "1234abcd",
      email: "axe@snapmail.cc",
      password: "MyPassword123"
    }
  ) {
    result {
      token
      storefrontLoginToken
      user {
        id
        bcId
        firstName
        lastName
        email
      }
    }
  }
}

Example GraphQL API Responses

With Storefront authToken only

{
  "data": {
    "login": {
      "result": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ",
        "user": {
          "id": "8889911",
          "bcId": 28,
          "firstName": "B2B",
          "lastName": "User",
          "email": "user@example.com"
        }
      }
    }
  }
}

With Storefront authToken and storefrontLoginToken

{
  "data": {
    "login": {
      "result": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InRlc3RfYjJjX29yZGVyX2ltcG9ydEBxcS5jb21tIiwic3RvcmVfaGFzaCI6ImYyb3N4ampueGoiLCJkYiI6ImRlZmF1bHQifQ",
        "storefrontLoginToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY",
        "user": {
          "id": "8889911",
          "bcId": 28,
          "firstName": "B2B",
          "lastName": "User",
          "email": "user@example.com"
        }
      }
    }
  }
}

Body

object | application/json

  • storeHash    string
    required

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

  • 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 storefront authToken.
    >= 1 characters
    Example: customer storefront token

  • password    string
    required

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

  • 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",
"channelId": 1000234,
"name": "customer storefront token",
"email": "user@example.com",
"password": "MyPassword123",
"beginAt": 1721900486,
"endAt": 1721900486
}

Response

OK

Body

object | application/json

  • code    number

    Default: 200

  • data    object

  • meta    object

example

{
"code": 200,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6ImtpZG8yNzZAc25hcG1haWwuY2MiLCJzdG9yZV9oYXNoIjoiMWk2enB4cGUzZyIsImRiIjoiZGVmYXVsdCIsIm5hbWUiOiJ0ZXN0OSIsImNoYW5uZWxfaWRzIjpbMV0sInRva2VuX3R5cGUiOjMsIm5iZiI6MTAwMCwiZXhwIjoyMDAxfQ.EiR__LVAlBVNYtFCZPWJYoPv6UfGiXtULxhK-BCQZjY",
"name": "customer storefront token"
},
"meta": {
"message": "SUCCESS"
}
}

See something you can improve? Edit this file on GitHub

Did you find what you were looking for?
OverviewGet Storefront authToken within Stencil