API Accounts

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.

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 an overview of the authentication schemes that our APIs use, see the Authentication section below.

API accounts

BigCommerce offers three types of OAuth-based API accounts to developers who wish to use BigCommerce’s REST APIs: store-level credentials, app-level credentials, and account-level credentials. This section describes the difference between the three, how to obtain and revoke account credentials, and the use cases for each. It also contains a reference for available OAuth scopes and provides a compelling list of reasons to migrate from legacy API tokens to OAuth credentials.

Every parent set of API credentials that you request for your store is its own API account. At its simplest, an API account consists of the following:

• The client_id uniquely identifies the app or user, or the client, making a request.
• The client_secret is a cryptographically secure value known only to the client and BigCommerce.

Every active API account has at least one access_token. Store-level API accounts include a static access token that does not change. App-level API accounts expect each application to generate a unique access token for every store that installs the app. Account-level API accounts include a single access token that belongs to the parent account of the store that the user is signed in to at the time of creation.

Guard these values closely. The client ID and client secret will never change; access tokens do not expire based on time and cannot be manually invalidated. It’s best practice to limit each account’s OAuth scope to only the privileges needed to complete that app or user’s designated tasks. Create separate API accounts for each app, store API user or function, or account-related implementation.

Choosing the right kind of API account

Where both types of API account are supported, review the preceding sections to make an informed choice about which best fits your use case.

Store-level API accounts

Merchants generate single-store API credentials when they create API accounts in their store control panel, in the Settings > Store-level API accounts menu. Use these credentials to read and change one store’s data with BigCommerce’s APIs. You can’t change store-level access tokens or OAuth scopes.

In addition to the API account components in the preceding section, store-level API accounts contain the following attributes out of the box:

• An access_token, which accompanies most REST API requests.
• The client name is a label for your convenience, and it doesn’t accompany requests.
• The API path is the URL to which you make requests. The API path won’t change, but it will have /v3/ or /v2/ appended to it, depending on the current version for the endpoint you’re querying.

Most APIs that work with store-level API accounts use the access_token to authenticate requests to BigCommerce. However, a few use the access token to generate a temporary credential. To learn more about special cases that involve store-level credentials, consult the documentation for the API you want to use.

Creating store-level API credentials

To create a store-level API account, consult our Knowledge Base article on Creating a Store API Account.

Revoking store-level API credentials

To revoke store-level API credentials, you must delete the corresponding store API account. If the client_id and client_secret are compromised, or the account has become unnecessary, secure your account by deleting the API account. You cannot recover a deleted API account, so take care.

To delete a store-level API account, consult our Knowledge Base article on Deleting a Store API Account.

App-level API accounts

You can create app-level API accounts in the Developer Portal. After a store owner or authorized user installs and authorizes an app, most apps use access tokens generated from the API account’s client ID, client secret, and a temporary grant code to read and change store data. Generate access tokens with the BigCommerce-initiated grant code authorization flow.

Some APIs use app-level API accounts to implement alternative authentication patterns. For a summary of all our authentication methods, see the authentication schemes described earlier in this article.

For more on working with apps, see our Guide to Building Apps. The sections on Implementing OAuth and Callback Handlers are particularly relevant to generating access tokens.

Creating app-level API credentials

To create an app and its associated API account, consult our article on Managing Apps in the Developer Portal.

App-level access tokens

App-level API accounts do not come pre-configured with an access token. Each time a store installs your app, BigCommerce initiates a grant code authorization flow to help your app generate a dedicated access token for that store. For further details, see Authenticating an app.

Revoking app-level API credentials

There is no way to manually revoke or force-regenerate app-level API account access tokens. However, either of the following actions triggers a token refresh:

• When the store owner’s email address changes
• When you modify the app API account’s OAuth scopes

After one of these changes, the store owner will be prompted to review the change and reauthorize the app the next time they click the app icon in the store control panel.

To delete an app-level API account, consult our article on Managing Apps in the Developer Portal.

Account-level API accounts

Account-level API accounts are designed to work with the GraphQL Account API, which manages resources beyond the scope of a single store. For example, managing control panel users in the BigCommerce ecosystem. Current and future features available using the GraphQL Account API toolset allow developers to build custom integrations and solutions that require high-level access to store and platform resources. Using this API, you can integrate with third-party applications, streamline and automate business processes, and manage multiple merchant stores per account.

Creating account-level credentials

To create an account-level API account visit the account control panel or the store control panel for a member store at Settings > Account-level API accounts.

To learn more about creating an account-level API account, consult our Knowledge Base article on API Accounts.

Account-level API credentials provide direct access to all the account’s stores, not just the store that was signed in at the time of creation. Their permissions are limited only by the OAuth scopes they were granted at the time of creation. Keep the access token and client secret secure.

Revoking account-level API credentials

An account-level access token is valid until the account is no longer active. However, you can manually delete account-level credentials.

To delete an account-level API account, visit the account control panel and find the account you want to delete in the list. Click the three dots in the Action column, then click Delete. Follow any prompts that appear.

Migrating from legacy to OAuth

Benefits of migrating to OAuth

We recommend migrating from legacy API credentials to OAuth, if you haven’t already. Migration provides a wealth of benefits, including the following:

• Unified requests: Send all OAuth requests to a single URL: https://api.bigcommerce.com. Using a common hostname prevents interruptions of service when a store’s domain or SSL/TLS certificate changes or expires.

• Latest and greatest APIs: BigCommerce’s V3 APIs are accessible exclusively with OAuth.

• Webhook subscriptions: OAuth API accounts can subscribe to real-time event notifications using BigCommerce’s webhooks.

• Shared secrets: Use new APIs and endpoints that require shared secrets, including the Customer Login and Current Customer APIs.

• Zippier responses: Responses to OAuth requests use gzip compression and less of your bandwidth.

• Better security with granular permissions: All OAuth tokens are scoped to specific operations and endpoints. If you suspect a breach, you will know which resources could be affected.

How to migrate

Before you update your API connections to use OAuth instead of legacy basic authentication, take the following actions:

• Create an API account appropriate to your use case. Keeping in mind the API endpoints your connections use, create either a store API account or an app API account per the preceding instructions. To adhere to industry-standard security practices, configure the account with the minimum OAuth scopes for your use case. If you’re using an app API account, you can always modify the scope later.
• If you use one of our client libraries, consult the library’s documentation for establishing an optimal OAuth configuration.
• After you create your connection, update your connection parameters as follows:
  • Use https://api.bigcommerce.com as the gateway URL instead of the BigCommerce store’s secure hostname. For example, route requests that formerly went to https://store-{{store_hash}}.mybigcommerce.com/api/v2/orders/{{order_id}} or https://my-custom-store-domain.com/api/v2/orders/{{order_id}} will now use https://api.bigcommerce.com/stores/{{store_hash}}/v2/orders/{{order_id}}.
  • Rewrite your HTTP request headers to use the X-Auth-Token header to pass the API account’s access_token instead of the Authorization header. For more information, see the access tokens section above.

Rate limiting works differently for OAuth API connections. For details, see the Rate Limits section of our API best practices article.

OAuth scopes

Scope grants and limits a program’s ability to read and write data. Set the scopes to the minimum level of access your implementation needs.

All OAuth scopes except default provide read-only permissions scopes so that you can limit some accounts to sending GET and HEAD requests.

Token creation scopes

Store resource scopes

Account resource scopes

Authentication

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

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

1
const customerJWT = (apiAccountClientId) => {
2
  let resource = `/customer/current.jwt?app_client_id=${apiAccountClientId}`;
3
  return fetch(resource)
4
  .then(response => {
5
    if(response.status === 200) {
6
      return response.text();
7
    } else {
8
      return new Error(`response.status is ${response.status}`);
9
    }
10
  })
11
  .then(jwt => {
12
    console.log(jwt); // JWT here
13
    // decode...
14
  })
15
  .catch(error => console.error(error));
16
}

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 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));
}

1
let endpoint = {
2
  route: "/carts?include=lineItems.physicalItems.options",
3
  method: "GET",
4
  accept: "application/json",
5
  // content: "application/json",
6
  success: 200
7
}
8
9
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

• Guide to Building Apps
• Rate Limits
• API Status Codes