Authentication

BigCommerce offers a suite of APIs that let you manage store data, sign customers in, make client-side queries for product information, and write apps that integrate third-party services into store operations.

This article provides an overview of the authentication schemes that our APIs use, organized by the header or other mechanism they use to authenticate with our servers.

Regardless of the subject API's authentication scheme, BigCommerce API accounts play a role in every authenticated request to our servers.

Our API accounts come in a few different flavors to meet the needs of different use cases. For example, app API accounts work well in multi-store contexts, whereas store API accounts are a good choice for frontend applications. Some endpoints only work with one kind of API account. For a thorough explanation of the differences, check out the section on choosing the right kind of API account in our API accounts article.

Stable tokens

Most of our APIs use credentials that do not expire based on a time frame. Depending on the type of API account the credentials belong to, they might expire based on user or developer actions.

The following sections describe the two authentication schemes we use that rely on stable tokens. They include example requests and list or describe the endpoints to which the schemes apply.

Access tokens

Most of our REST endpoints and GraphQL Admin API endpoints use the X-Auth-Token header to authenticate to BigCommerce servers. For more about the APIs that do NOT use the X-Auth-Token header, consult this article's sections on dynamic tokens and same-origin CORS authentication.

The X-Auth-Token header uses access tokens to authenticate requests. Create an OAuth API account to generate access tokens. Pass the access token as the value of the X-Auth-Token header of the request you want to authenticate.

For a request to succeed, the access token's API account must have permission to receive the response. Configure your API account with the minimum set of OAuth scopes that your implementation needs.

To find the specific OAuth scopes your requests require, consult the root API reference pages for the families of endpoints you plan to use. For example, see the OAuth scopes for the Email Templates endpoints. We also maintain a list of all our OAuth scopes.

X-Auth-Token header example requests

The following tabs contain examples of how to authenticate requests by passing an access token to the X-Auth-Token header.

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v... # endpoint
X-Auth-Token: {{access_token}}
Accept: application/json

Client ID

Another stable token-based scheme involves mutual authentication. The requesting app identifies itself by sending an API account's client ID as a query parameter, and our servers return a BigCommerce-generated JSON web token, or JWT, which securely encrypts merchant data. The app can decode the JWT to view the response. For example, the Current Customer API's JWT payload identifies the currently signed-in customer.

The following table lists the APIs that authenticate with a client ID. For OAuth scopes, consult the Endpoint Reference column.

Current Customer API example request

const customerJWT = (apiAccountClientId) => {
  let resource = `/customer/current.jwt?app_client_id=${apiAccountClientId}`;
  return fetch(resource)
  .then(response => {
    if(response.status === 200) {
      return response.text();
    } else {
      return new Error(`response.status is ${response.status}`);
    }
  })
  .then(jwt => {
    console.log(jwt); // JWT here
    // decode...
  })
  .catch(error => console.error(error));
}

Dynamic tokens

Several of our APIs authenticate with JSON web tokens, or JWTs. JWTs authorize both the requester and the recipient because they contain a signed payload that the recipient must successfully decrypt before working with the transmitted data. You can use some JWTs for any number of requests within an expiration window; others must be unique to each request.

Our JWT-based authentication schemes fall into the following categories:

• The user passes a BigCommerce-generated JWT as part of the value of the Authorization header
• The user sends BigCommerce a user-generated JWT
• BigCommerce-encrypted payload JWTs send apps information as part of a signed JWT's payload

All requests that use JWTs require at least two steps. In addition to the request itself, you must also either get, make, or decrypt the JWT that the request sends or receives. The following sections describe the steps for these three JWT-based authentication schemes, reference the endpoints to which they apply, and give example requests.

BigCommerce-generated JWTs

Some APIs authenticate with an Authorization header that contains a string concatenated with a BigCommerce-generated JWT. Requests to these APIs contain the following two parts:

1. The user obtains the JWT by:
   • Making an API request to BigCommerce, or
   • On Stencil storefronts, extracting it from the page's context.
2. The user sends the intended request.

The following table lists the APIs that use the Authorization header, along with information about obtaining a token and forming a valid header value. For OAuth scope, expiry window, and other implementation details, consult the Endpoint Reference column.

To obtain a dynamic token, send a request to the REST endpoint listed in the Obtain a JWT column or consult the article listed in the API Description column. Use an API account with the appropriate token creation scope for the kind of tokens you wish to generate.

Authorization header example requests

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/some-token-generating-endpoint
X-Auth-Token: {{access_token}}
Accept: application/json
Content-Type: application/json
 
{
  // request body per token request endpoint documentation
}

User-generated JWTs

Some APIs rely on the app or implementation to send user-generated JWTs that simultaneously authenticate the request and contain the request body in their payload. Requests to these APIs contain the following two parts:

• The user encrypts, or signs, the JWT
• The user sends the intended request

The following table lists the APIs that rely on user-generated JWTs. For OAuth scope, expiry window, and other implementation details, consult the Endpoint Reference column.

Customer Login API example request

For the Customer Login API, your request will look something like the following:

const loginCustomer = (yourJwt) => {
  let resource = `${window.location.origin}/login/token/${yourJwt}`;
  return fetch(resource)
  .then(response => {
    console.log(response);
    if(response.status === 200) {
      // resolve any parts of the response to work with...
      return Promise.all([response.url, response.text()]);
    } else {
      return new Error(`response.status is ${response.status}`);
    }
  })
  .then(([url, content]) => {
    console.log(url); // navigate to URL, or
    console.log(content); // work with page content
    // etc...
  })
  .catch(error => console.error(error));
}

BigCommerce-encrypted payload JWTs

BigCommerce-encrypted payload JWTs let control panel apps listen to and reason about events that affect them, but happen outside the app itself. These events include users installing, loading, and uninstalling the app. Working with these JWTs includes the following parts:

• The app receives the JWT from BigCommerce
• The app validates the JWT, then decrypts its payload
• The payload's data informs what the app does next

To learn more, see our Apps Guide, especially the articles on authorization, installation, and other app callback events.

Same-origin CORS authentication

The following APIs rely on CORS (opens in a new tab) headers for authentication. You do not need to send any BigCommerce-specific tokens with your requests to these endpoints.

REST Storefront API

The REST Storefront API lets you make client-side requests for carts, checkouts, and orders using JavaScript or an alternative language that compiles to run in the browser. It is a convenience collection of operations that affect one customer at a time and run in the context of the customer's current session on a BigCommerce-hosted storefront. You can perform authenticated versions of the same operations using the GraphQL Storefront API or the REST Store Management APIs.

The following examples illustrate how to make calls to the REST Storefront API:

const storefrontCall = (endpoint, requestBody = null) => {
  let resource = `${window.location.origin}/api/storefront${endpoint.route}`;
  let init = {
    method: endpoint.method,
    credentials: "same-origin",
    headers: {
      // note: no authorization
      "Accept": endpoint.accept,
    }
  }
  if(requestBody) {
    init.body = JSON.stringify(requestBody);
    init.headers["Content-Type"] = endpoint.content;
  }
 
  return fetch(resource, init)
  .then(response => {
    console.log(response);
    if(response.status === endpoint.success) {
      // resolve promise using the Fetch API method that correlates with the endpoint.accept value
      return response.json(); // or response.text()
    } else {
      return new Error(`response.status is ${response.status}`);
    }
  })
  .then(result => {
    console.log(result); // requested data
    // do stuff...
  })
  .catch(error => console.error(error));
}
 

let endpoint = {
  route: "/carts?include=lineItems.physicalItems.options",
  method: "GET",
  accept: "application/json",
  // content: "application/json",
  success: 200
}
 
storefrontCall(endpoint);
 

Developer-configured authentication

REST Provider APIs

Unlike our other APIs, we do not host the REST Provider APIs. The Provider API specifications describe requests that BigCommerce sends the provider app's server, and the responses that we expect in return.

The following table describes the authentication characteristics of our REST Provider APIs.

In the Tax Provider API Authorization header, the username and password belong to the app's tax provider service. What this username and password actually refer to is up to the app developer.

Resources

Related articles

• Creating API Accounts
• OAuth Scopes