Authentication for hosted storefronts

Authentication provides vital security for your application by verifying who can access certain data. B2B Edition provides several methods for retrieving tokens that can be used to authenticate requests to server to server and storefront APIs.

Server-to-Server Tokens

BigCommerce API authentication tokens are used to authenticate requests to the B2B REST Management API. These tokens use specially managed scopes for B2B Edition and are configured ahead via the BigCommerce control panel.

Creating an API Account

Creating an API Account is recommended for backend users who need access to relevant account features, company management, and other tasks available through the B2B REST Management API.

The process for setting up a store-level token is dependent on the appropriate BigCommerce permissions being enabled. Specifically, only users with the Create store-level API Accounts permission enabled can set up the necessary token.

To create a token for server-to-server requests,

1. Navigate to Settings > Store-level API accounts in the BigCommerce Control Panel.
2. Click Create API Account.
3. Create a V3 Token with the B2B Edition scope set to modify.
4. Save the relevant account keys for future reference.

For more information on creating and managing API accounts, refer to API Accounts (Help Center) (opens in a new tab).

Using the REST Management API

When using the B2B REST Management API, two header parameters are required for authentication: access token and store hash. Both are returned in the API account creation process. Specifically, your requests should include the headers

• X-Auth-Token - The ACCESS TOKEN provided during API account creation. This is required for authentication across all server-to-server endpoints.
• X-Store-Hash - The STORE HASH provided during API account creation. This hash is unique to the store, but not to the account. This ensures requests are made to the appropriate B2B Edition account.

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

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]

async function() {
  try {
    let authToken = await fetch({
      method: "post",
      url: "https://api-b2b.bigcommerce.com/api/v3/io/auth/backend",
      body: {
        storeHash: "<STORE_HASH>",
        email: "<USER_EMAIL>",
        password: "<USER_PASSWORD>",
        channelId: 1,
        name: "optionalTokenName",
        beginAt: 1000,
        endAt: 17219304, // Unix timestamp for expiry
      }
    });
    return authToken;
  } catch(error) {
    console.log(error);
    throw error;
  }
}

Tokens created via API can be invalidated as necessary using the Delete Backend API Tokens endpoint.

For more details, see the B2B Edition Settings (opens in a new tab).

Storefront Tokens

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

Certain requests are considered anonymous and do not require a storefront authToken for validation. This includes requests that can be performed as a guest shopper without an account, such as the companyCreate mutation, as well as mutations that generate tokens themselves.

To view or modify data from the context of a storefront user with an account, you must authenticate it by including a storefront authToken passed with the Authorization header. Storefront authTokens have the following differences from server to server authToken:

• They are bearer tokens tied to a specific user.
• They automatically expire after 1 day. Refresh a storefront authToken with a new request.
• A storefront authToken’s scope depends on the corresponding user.
  • For example, a token generated for a B2C customer authenticates any request that does not require a Company account, while one for a B2B buyer can only authenticate a request if the buyer’s Company user account has the corresponding permissions enabled.

The BigCommerce GraphQL Storefront API 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 do not rely on storefront cookies.

The sections below provide information about the different methods for generating a storefront authToken. All methods can be used in both Stencil and headless storefronts.

The login Mutation

The login mutation allows you to gather an authToken with the credentials used by Company users to log in to the Buyer Portal. This request is performed independently of a standard customer session in the storefront, but you can sync their login by including the storefrontLoginToken field in the request.

The storefrontLoginToken field returns a JSON Web Token (JWT) signed with the B2B Edition client secret. To sync the login with a storefront session, pass the JWT to the Customer Login endpoint.

The examples below include the request body and variables for generating a storefront authToken and JWT with user details, as well as the expected response.

mutation LogIn(
    $storeHash: String!,
    $email: String!,
    $password: String!
) {
  login(
    loginData: {
      storeHash: $storeHash,
      email: $email,
      password: $password
    }
  ) {
    result {
      token
      storefrontLoginToken
      user {
        id
        bcId
        firstName
        lastName
        email
      }
    }
  }
}

{
    "storeHash": "{The BigCommerce store hash}",
    "email": "{The Company user email address}",
    "password": "{The Company user password}"
}

{
    "data": {
        "login": {
            "result": {
                "token": "{storefront authToken)",
                "storefrontLoginToken": "{JWT}",
                "user": {
                    "id": "12345",
                    "bcId": 123,
                    "firstName": "Marie",
                    "lastName": "Curie",
                    "email": "mcurie@greatbuysinc.com"
                }
            }
        }
    }
}

To learn more about the login mutation, see our storefront authentication documentation.

The authorization Mutation

If you want your integration to use an existing storefront session for a logged-in Company user to generate a storefront authToken, you can accomplish this with the authorization mutation. The request uses a JWT to retrieve a token that can be used to authenticate further requests to the GraphQL API while the user is logged in.

To obtain a JWT for validation, make a request to the BigCommerce Current Customer API while passing the B2B Edition client ID (dl7c39mdpul6hyc489yk0vzxl6jesyx) with the app-client-id query parameter.

Here’s an example of a Fetch request that you can use to obtain a JWT for B2B Edition. Replace the example domain in the endpoint with your store’s domain.

const options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'}
};
 
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));

You can pass the resulting JWT to the authorization mutation without decoding it. The request can be structured as follows:

mutation userAuth(
	$bcToken: String!,
	$channelId: Int!
) {
    authorization(
        authData: {
            bcToken: $bcToken,
	     channelId: $channelId
        }
    ) {
        result {
            token
        }
    }
}

{
	"bcToken": "{The JWT for the storefront session}",
	"channelId": {BigCommerce storefront channel ID; use 1 for the default channel}
}

{
    "data": {
        "authorization": {
            "result": {
                "token": "{storefront authToken}"
            }
        }
    }
}

See our article on storefront authentication to learn more about this mutation’s usage and fields.

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.

Get Storefront authToken with Credentials

Like the login mutation, this endpoint validates a Company user’s login credentials to create a storefront authToken for future requests. The resulting token has the default validity period of 1 day, but you can use the beginAt and endAt fields in the request body to specify a custom period.

See our server to server authentication documentation for information on formatting the request.

Get a B2B Storefront Token

The Get a B2B Storefront Token endpoint only requires a customer ID to retrieve a storefront authToken. However, this token does not automatically sync with a storefront session.

To sync a login with the token, you must include a customer access token (CAT) in the request body. You can retrieve a CAT by using the login mutation of the BigCommerce GraphQL Storefront API, not the equivalent request in the B2B Edition GraphQL Storefront API.

Get a Storefront API authToken

Rather than targeting a specific Company user, this endpoint retrieves an existing storefront authToken based on the JWT associated with an active storefront session. As with the authorization mutation, you can use the Current Customer API to retrieve a JWT and pass it to the jwtToken query parameter of the request. Here are two examples of how you can format the request:

curl https://api-b2b.bigcommerce.com/api/io/auth/storefront?jwtToken=bigCommerce.currentCustomerResponse.jwtString&channelId=1

async function() {
  try {
    let authToken = await fetch({
      method: "get",
      url: "https://api-b2b.bigcommerce.com/api/io/auth/storefront",
      query:{
        jwtToken: "bigCommerce.currentCustomerResponse.jwtString",
        channelId: 1
      }
    });
    return authToken;
  } catch(error) {
    console.log(error);
    throw error;
  }
}

Resources

• Authentication (Server to Server)
• Authentication (Storefront)
• Current Customer
• Authenticating requests to the GraphQL Storefront API