Getting Started
About Stencil
Transitioning to Stencil
Installing Stencil
Authentication & Tokens
Running Stencil Locally
Advanced Installation Options
Template Files
Templates Directory
Custom Templates
Customize Stencil Checkout
Handlebars and Stencil
Handlebars.js Overview
Handlebars Helpers
Stencil Object Model
Stencil Objects

Creating an API Account to Obtain OAuth Tokens

Status Check

If you’ve successfully installed Stencil you’re ready to create a BigCommerce API Account. If you have not yet installed Stencil, see Installing Stencil.

Creating an API Account

Follow the steps below to create an API Account and obtain your OAuth Tokens.

  1. Using the store owner’s credentials, log into the control panel of the store for which you are developing.

  2. From the left nav, select Advanced Settings > API Accounts.

  3. From the resulting Store API Accounts page, select the Create API Account button.

  4. Give your account a name that reflects its purpose.

The BigCommerce platform does not validate this name, however, we recommend naming accounts by purpose to help you keep track of which accounts you need to keep active. You should assign a name that will make the account’s purpose clear to you and other store administrators.

  1. Under OAuth Scopes, set the Themes selector to either modify or read-only.

The read-only scope is sufficient to authorize/initialize a Stencil theme. However, the modify scope will achieve the same goal, while also authorizing this account to upload themes to the store from the command line.

  1. Click Save.

Doing so will display a modal, from which you can copy your Client ID and Access Token values. The modal will also prompt your browser to download a .txt file that contains your credentials. You will need these values to authorize and initialize your Stencil theme. If you’re ready to do so now, move ahead to Authorizing and Initializing Stencil.

Reserved Role

Currently, only the store owner can create an OAuth API account according to the instructions below. Also, note that each store is limited to 50 accounts at a time.

Issuing Additional Tokens

To issue store tokens for additional themes or developers, repeat the process outlined in Creating an API Account.

(Even if you originally initialized your theme using a legacy API [Basic-Auth] token, you will need to generate any new tokens using the new OAuth flow.)

You can create up to 50 API accounts/tokens per store. If you hit this limit and still need to create new tokens, you will need to delete existing accounts. Deleting an account will invalidate the corresponding token, which will affect any developer using that token.

Revoking OAuth Tokens

Note: After completing the below process, there is no undo. The following process completely deletes the selected account(s), revoking the corresponding token(s).

If you are completely sure you would like to revoke an existing OAuth store token, delete the corresponding Store API account with the following steps:

  1. Navigate to the Control Panel’s API Accounts page.
  2. Select the trash-can button to the right of the account that you want to delete1.
  1. You can also use the check boxes at left to select multiple accounts to delete them all at once.

Copying OAuth Tokens

To access an existing OAuth token to authorize your theme:

  1. Open the .txt file2 that the BigCommerce control panel generated when you created the API account.

  2. Note the Client ID and Access Token hashes in the file (or in the control-panel modal for your newly created token).

  3. If you are a merchant granting an outside theme developer access to your store, provide the Client ID and Access Token values to the developer. The developer will need these when Authorizing and Initializing Stencil. If you are a merchant developing a theme against your own store, you will use the same two values in the same Authorizing and Initializing Stencil step.

  1. If you did not retain this file, you will need to generate a new token by repeating the Creating an API Account procedure