Codinative

BigCommerce guidelines

How to create API access for a BigCommerce store, the difference between v2 and v3, and the token you need for Stencil theme development.

How authentication works

Almost everything you build against a single store - the REST API (v2 and v3) and the GraphQL API - uses one thing: a store-level API account access token, sent on every request as the X-Auth-Token header.

The base URL for a store is always:

https://api.bigcommerce.com/stores/{store_hash}/...

The {store_hash} identifies the store (you can see it in the control-panel URL, e.g. store-abc123 means the hash is abc123).

1. Create a store-level API account

  1. In the store control panel go to Settings → API → Store-level API accounts.
  2. Click Create API account, give it a clear name (e.g. codinative-signup-app).
  3. Choose the OAuth scopes the integration needs - set each resource to none / read-only / modify. Grant the minimum required.
  4. Click Save. A credentials file downloads containing the Client ID, Client Secret, Access Token, and API Path.
The access token is shown once. Store it in the dashboard secrets vault or your password manager - never commit it to a repo or paste it in chat. If it leaks, delete the API account and create a new one.

2. Use the token

Send the access token as the X-Auth-Token header on every request:

curl https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products \
  -H "X-Auth-Token: {access_token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

3. v2 vs v3 - versions, not separate tokens

A common point of confusion: v2 and v3 are API versions, not two different kinds of token. The same store API account token works for both - the scopes you granted decide what it can do, regardless of version.

  • v3 - the modern API. Use it whenever a resource exists there (catalog / products, customers, etc.). Clean JSON, consistent pagination via meta.pagination.
  • v2 - the legacy API. Still required for a few resources that were never moved to v3 (orders are the classic example).

Rule of thumb: prefer v3, and fall back to v2 only for resources that are not available in v3.

App OAuth tokens (for published apps)

Store API accounts are for back-office scripts and single-store integrations. Our embedded apps (signup forms, shipping rules, sticky add-to-cart) instead use app-level OAuth tokens: when a merchant installs the app, BigCommerce sends an auth code that the app exchanges for a per-store access token. Same X-Auth-Token header afterwards, but the token is obtained through the OAuth install flow rather than created by hand.

Stencil CLI token (theme development)

Stencil is BigCommerce’s toolkit for developing Stencil storefront themes locally. It authenticates with a store API account access token - the “Stencil token”.

  1. Create a store-level API account (step 1 above) with read access to Information & Settings, Content, and Themes (check the current Stencil docs for the exact scope list). Copy its access token.
  2. Install the CLI:
    npm install -g @bigcommerce/stencil-cli
  3. Initialise the theme folder - it prompts for the store URL and the token:
    stencil init
    This writes a .stencil file (which holds the token, so it is git-ignored - never commit it).
  4. Preview locally, then bundle and push:
    stencil start      # local preview
stencil push       # bundle + upload the theme

Where to keep tokens

Put store tokens and secrets in the dashboard secrets vault (team sign-in required) rather than in .env files committed to a repo. Treat every access token like a password.

Official references