Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 28 ยท REST APIs

API Accounts, Tokens and Scopes

Learn how BigCommerce API accounts, access tokens and OAuth scopes work, how to apply least privilege, store tokens safely and diagnose 401 and 403 errors.

Every request to the BigCommerce REST APIs must prove who is calling and what that caller may do. BigCommerce answers both questions with one credential: an access token that is tied to one store and carries a fixed set of OAuth scopes. If you understand tokens and scopes, most authorization errors become easy to diagnose, and you can design integrations that do little damage when something leaks.

This lesson covers store-level API accounts (the kind you create for your own scripts), how a token is sent, how scopes map to endpoints, and how to apply least privilege. The real platform calls are read-only here. The runnable stand-in is a scope checker in Node.js that mimics the decision the platform makes. The scope names in the stand-in follow the real naming style, but the mapping table is our own simplified model.

Store-level API accounts

You create a store-level API account in the control panel, in the advanced settings under API accounts. You pick a name and, for each area, a permission level: usually None, Read-only or Modify. After you save, BigCommerce shows the client id, client secret and access token exactly once, and offers a downloadable credentials file. If you lose the token, you create a new account (or a new token) and update your scripts.

Behind the scenes, those permission choices become OAuth scopes. A scope is just a string that names an area and an access level. Typical examples of the naming style are store_v2_products, store_v2_products_read_only, store_v2_orders and store_v2_customers. The names look V2-flavored for historical reasons, but they also govern V3 endpoints in the same area. Always read the endpoint's documentation to see which scope it needs, and don't guess from the name.

This kind of account is meant for your own store or a store you manage. If you build something that many merchants install, you use the OAuth app flow instead, where the merchant approves your requested scopes at install time. See App Types and the OAuth Flow.

Sending the token

Requests carry the token in the X-Auth-Token header, on HTTPS only (read-only):

HTTP
GET /stores/abc123xyz/v3/catalog/products?limit=5 HTTP/1.1
Host: api.bigcommerce.com
X-Auth-Token: <access token>
Accept: application/json

Some older documentation also mentions an X-Auth-Client header holding the client id. Modern store-level accounts rely on the token. Never put the token in a query string, a front-end bundle or a public repository. A browser-side script that needs data should use the Storefront GraphQL API with a limited storefront token, which is a different credential designed for public use (see GraphQL Storefront API).

401 versus 403

Two status codes tell you what went wrong:

  • 401 Unauthorized: the platform could not authenticate you. The token is missing, mistyped, revoked or belongs to another store.
  • 403 Forbidden: the token is valid, but its scopes do not allow this call. The fix is to add the scope in the API account (and create a fresh token if the platform asks you to) or to use another endpoint.

A third failure is subtle: a 404 can appear when you use the wrong store hash, because the path then points to a store that does not exist for your token.

flowchart TD
    R["Request with X-Auth-Token"] --> A{"Token valid<br/>for this store?"}
    A -->|"no"| E1["401 Unauthorized"]
    A -->|"yes"| B{"Scope allows<br/>this endpoint and method?"}
    B -->|"no"| E2["403 Forbidden"]
    B -->|"yes"| OK["Request runs"]

The platform authenticates first (401), then authorizes by scope (403).

Least privilege

Least privilege means each credential gets the minimum permissions for its job. For API accounts this gives concrete rules:

  • A reporting script that only reads orders gets orders read-only, nothing else.
  • A product sync gets products modify, but no customer access.
  • Use one API account per integration. If the nightly job leaks its token, you revoke that account and nothing else breaks.
  • Prefer read-only wherever it works. A leaked read-only token can expose data, but it cannot alter or delete it.
  • Review accounts regularly and delete the ones you no longer use.

This is the same reasoning as in Shop Security Basics: limit the blast radius of an unavoidable leak.

Storing tokens

Treat the token like a password. Keep it in environment variables or a secret manager, load it once at start-up (see Setting Up a Development Environment), and never log it. For apps that serve many stores, you must store one token per store, ideally encrypted at rest; Building an App Backend shows a pattern. If a token appears in a commit, assume it is compromised: revoke it first, then clean up history.

A scope checker stand-in

The real platform checks scopes on its own servers. The stand-in below does the same decision locally so you can see the rules. It has a small table of endpoints, each needing a scope for reads and a scope for writes. A read-only scope allows only GET. The scope naming follows the real style, but the exact set of scopes per endpoint is simplified, so always consult the official reference for the real mapping.

Node.js Which requests does this token allow?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The report token can read orders but is refused when it tries to change one (PUT) or to read the catalog. The sync token can write products but cannot read customers. A missing token gives 401, an insufficient one gives 403, which is the same split you will see from the real API.

Auditing a token set

A single script can check, before deployment, whether the scopes you requested are broader than the endpoints your code actually calls. That is a cheap way to enforce least privilege in CI. The second stand-in compares a list of calls your integration makes against its scopes and flags both missing scopes and unused extra ones.

Node.js Audit scopes against the calls you make

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first token set is too broad: orders only needs read access and customers is unused. The second set matches exactly. Running such a check in your pipeline keeps scope creep visible.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A call returns 403 although the token is valid. What should you check first?

    403 means authenticated but not permitted. The scopes of the API account decide permission.
  2. 2. Which credential is safe to expose in browser JavaScript?

    Storefront tokens are designed for public use and have a limited reach. Admin tokens must stay on your server.
  3. 3. What does "one API account per integration" achieve?

    Separate accounts limit the blast radius and make it clear which job used which token.
  4. 4. Where is the access token sent in a REST request?

    The header keeps the token out of URLs and logs.
  5. 5. A token has a read-only scope for orders. Which request fails with 403?

    Read-only scopes allow reads only. Changing an order needs a modify scope.

Summary

  • A store-level API account yields a client id, secret and access token, shown once.
  • Scopes name an area and an access level; the token is sent in X-Auth-Token.
  • 401 means not authenticated, 403 means authenticated but not allowed.
  • Apply least privilege: read-only where possible, one account per integration, regular reviews.
  • Store tokens in env files or secret managers, never in code, URLs or logs.

Next: The Catalog API (V3)