Authenticating BigCommerce’s REST APIs

Two types of API credentials are available to developers wishing to make requests against BigCommerce’s REST APIs:

1. Store API Credentials (created in a store’s control panel)
2. App API Credentials (created in the Developer Portal)

Store API Credentials are generated when a Store API Account is created in a store’s control panel (Advanced Settings > API Accounts). These credentials are used to programmatically interact with an individual store’s data using BigCommerce’s APIs. Both OAuth and token-based authentication are possible with Store API Credentials

Developers can also create App API Credentials in the BigCommerce Developer Portal. App API Credentials are used during the OAuth flow to request authorization “on behalf” of a store owner, allowing the app to make API requests against store data. App API Credentials are OAuth only, and the store owner must install the app before the app is granted access to the store.

Obtaining Store API Credentials

To generate store API Credentials, log into the store, then:

1. Navigate to Advanced Settings > API Accounts > Create API Account.
2. Give the account a name (internal only).
3. In the OAuth Scopes section, select the minimum scopes the app will require.
4. Select Save.

A successful save will display a pop-up containing the API credentials that your app will need to run authenticated requests – your Client ID and Access Token. A .txt file containing the same credentials will (on most browsers) automatically download to your computer. This file also contains the base API Path for your store, preconfigured for the v3 API.

The base api path will look something like this: https://api.bigcommerce.com/stores/123456/. In the base path, the store hash is the 123456. This will be used to make API requests.

To get started making requests, see API Requests.

Revoking Store API Credentials

To revoke Store API Credentials:

1. Log into the store, using the store owner’s username/password.
2. Select Advanced Settings.
3. Select API Accounts. This will display the Store API Accounts page, shown below.
4. In the Actions column at right, select the trash-can button next to the account you want to delete.

Obtaining App API Credentials

To get App API Credentials, login to (or create) your BigCommerce Developer Portal account. Navigate to My Apps (top-right corner), then:

1. Click Create an app
2. Give your app a name (only be visible to you)
3. Click Create (a pop up box will display showing Your Profile, App Summary and Category)

1. Click on Step 3 - Technical. Fill out the App Features sections with App Type, Callback URLs and Scope.

Step 3 - Technical

1. In the lower right-hand corner of the popup box, click Update & Close.
2. A new pop up will show asking if you want to change the OAuth Scopes. Click Confirm Update.
3. You will be routed back to the Dev Tools home page and your app will be listed. Click View Client ID.

1. Copy your Client ID and Client Secret. The Client ID and Client Secret can be accessed at any time by clicking View Client ID.

Next Steps

During the app installation process, your app will use the Client Id and Client Secret to obtain an Oauth token authorized against the store installing the app. For a detailed look at this process, see Building an App.

Use Cases by Credential Type

App API Credentials	Store API Credentials
From Dev Tools	X
From Store Control Panel
Single Click Apps (Marketplace)	X
Private Apps	X
Hidden Apps	X
Connector Apps
Scripts
Testing
V2	X
V3	X
Webhooks	X

Migrating from Legacy to OAuth

Migrating to OAuth comes with several benefits:

• All OAuth requests are sent to a common hostname: https://api.bigcommerce.com. Using a single hostname prevents any interruption of service when the domain or SSL on a particular store changes or expires.

• All of BigCommerce’s newest V3 APIs are exclusively available via OAuth.

• OAuth API accounts have access to subscribe to BigCommerce’s Webhooks for real-time event notifications

• The ability to use new APIs that require a shared secret, such as the Storefront Login API or the Storefront Current Customer identification endpoint.

• Gzip compression on API responses to reduce bandwidth usage

• Better security as all OAuth tokens are scoped to particular endpoints

How to Migrate

First, consider whether your application should reside within the public App Marketplace, where any BigCommerce merchant can quickly discover and install it. To learn more about how to set up this kind of app, see Becoming a Partner.

If you would like to update your API connection from Basic Authentication to OAuth, you will need to make the following changes:

• Get a Client ID and an Access Token, by creating an API Account within the control panel. You’ll want to make sure the account has the correct Scopes for the API endpoints you need to access. We recommend that you provide the minimum scopes that your application requires to function, as a good security practice.
• If you use one of the Client Libraries, follow the relevant guide (within the library’s documentation) for establishing an OAuth connection.
• If you have created your connection, you’ll want to update your connection parameters:
  • Where you previously used the BigCommerce store’s secure hostname, you will instead use the https://api.bigcommerce.com gateway URL. As an example, requests to https://store-abc123.mybigcommerce.com/api/v2/orders/123 or https://my-custom-store-domain.com/api/v2/orders/123would instead go to https://api.bigcommerce.com/stores/{store_hash}/v2/orders/123.
• With Basic Auth, you use an Authentication HTTP Header to authenticate your connection. With OAuth, you’ll want to use two headers:
  • X-Client-Id for your Client ID
  • X-Auth-Token header for your Access Token. You can read more here.

Rate limiting of API requests works differently for OAuth API connections. To become familiar with the OAuth system, please see the Rate Limits.

OAuth Scopes

Scope limits ability to read or write to data. Set the scope to the minimum level needed to accomplish the task at hand.

All OAuth scopes except default have read_only scopes that allow only GET and HEAD requests.

• Webhooks are accessible from the default scope that is available when API Credentials are created.
• Wishlists API is accessible with Customers scope.

Scope GUI Name	Resources	Description
Content	store_v2_content	View and modify store content
		/v2/pages
		/v2/blog
		/v2/redirects
		/v3/widgets
	store_v2_content_read_only	View Site Content
		/v2/pages
		/v2/blog
		/v2/redirects
		/v3/widgets
Checkout Content	store_content_checkout	View and modify content on checkout pages
		/v3/scripts
	store_content_checkout_read_only	View content on checkout pages
		/v3/scripts
Customers	store_v2_customers	View and modify customer information
		/v2/customers
		/v2/customer_groups
		/v3/customers/subscribers
	store_v2_customers_read_only	View customer information
		/v2/customers
		/v2/customer_groups
		/v3/customers/subscribers
Customers Login	store_v2_customers_login	Log in customers to your storefront
		Access to the Customer Login API
Information & Settings	store_v2_information	View and modify general store information and settings
		/v2/shipping/methods
		/v2/shipping/zones
		/v2/shipping/carrier
	store_v2_information_read_only	View general store information and settings
		/v2/shipping/methods
		/v2/shipping/zones
		/v2/shipping/carrier
		/v2/payments/methods
		/v2/tax_classes
		/v2/store
Marketing	store_v2_marketing	View and modify marketing information
		/v2/coupons
		/v2/gift_certificates
		/v2/banners
	store_v2_marketing_read_only	View marketing information
		/v2/coupons
		/v2/gift_certificates
		/v2/banners
Orders	store_v2_orders	View and modify orders
		/v2/orders
		/v2/order_statuses
	store_v2_orders_read_only	View orders
		/v2/orders
		/v2/order_statuses
Order Transactions	store_v2_transactions	View and modify order transactions
		/v3/orders/{id}/transactions
	store_v2_transactions_read_only	View order transactions
		/v3/orders/{id}/transactions
Create Payments	store_payments_access_token_create	Process Payments
		/payments/access_tokens
Get Payment Methods	store_payments_methods_read	Get Order Payment Methods
		/payments
Products	store_v2_products	View and modify products, brands, categories and other product information.
		/v3/catalog
		/v3/pricelists
	store_v2_products_read_only	View products
		/v3/catalog
		/v3/pricelists
Themes	store_themes_manage	View and modify themes
		/v3/themes
	store_themes_read_only	View themes
		/v3/themes
Carts	store_cart	View and Modify carts
		/v3/carts
	store_cart_read_only	View Carts
		/v3/carts
Checkouts	store_checkout	View and modify a checkout
		/v3/checkouts
	store_checkout_read_only	View checkout content
		/v3/checkouts
Sites & Routes	store_sites	View and modify sites and routes
		/v3/channels/{channel_id}/site
		/v3/sites/{site_id}/routes
	store_sites_read_only	View external storefronts with Non-BigCommerce URLs
		/v3/channels/{channel_id}/site
		/v3/sites/{site_id}/routes
Channel Settings	store_channel_settings	View and modify a list of channels
		/v3/channels
	store_channel_settings_read_only	View a list of channels
		/v3/channels
Channel Listings	store_channel_listings	View and modify a list of all channel listings for a particular channel
		/v3/channels/listings
	store_channel_listings_read_only	View a list of all channel listings for a particular channel
		/v3/channels/listings
Storefront API Tokens	store_storefront_api	Create a storefront API token
		/v3/storefront/api-token
Storefront API Customer Impersonation Tokens	store_storefront_api_customer_impersonation	Create a storefront API token that allows for customer impersonation
		/v3/storefront/api-token-customer-impersonation

Resources

• Building An App
• Rate Limits