Authenticating BigCommerce’s REST APIs
On This Page
Two types of API credentials are available to developers wishing to make requests against BigCommerce’s REST APIs.
Store API credentials
Store API credentials are generated when a store API account is created in a store’s control panel (Advanced Settings > API Accounts). You can use these credentials 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.
App API credentials
Developers can 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
The following steps outline how to generate store API Credentials.
- Navigate to Advanced Settings > API Accounts > Create API Account.
- Give the account a name (it will only be visible to store users).
- In the OAuth Scopes section, select the minimum scopes the app will require.
- Select Save.
A successful save will display a pop-up containing an Access Token. Your app will need this credential to run authenticated requests. 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
. You will use this to make API requests.
To get started making requests, see API Requests.
Save your credentials
There is no way to re-display this pop-up after selecting Done, so be sure to securely store the credentials before exiting this screen.
Revoking store API credentials
To revoke Store API Credentials:
- Log into the store, using the store owner’s username/password.
- Navigate to Advanced Settings > API Accounts and click the check box next to the account you want to delete.
- In the Actions column at right, click the trash can icon.
Delete carefully
Deleting an account cannot be undone, so be sure before clicking the trash can icon. You can also use the checkboxes on the left side to delete multiple accounts at once – but be especially careful when using this option.
Obtaining app API credentials
To get app API credentials, create and log into your BigCommerce Developer Portal account. Navigate to My Apps in the top-right corner, then:
- Click Create an app.
- Give your app a name. This name will only be visible to you.
- Click Create. A pop-up box will display showing Your Profile, App Summary, and Category.
- Click on Step 3 - Technical. Fill out the App Features sections with app type, callback URLs, and scope.
Step 3 - Technical
- In the lower right-hand corner of the popup box, click Update & Close.
- A new pop up will show asking if you want to change the OAuth scopes. Click Confirm Update.
- You will be routed back to the Developer Portal home page and your app will be listed. Click View Client ID.
- Copy your client ID and client secret. The client ID and client secret can be accessed by clicking View Client ID.
Client ID and client secret
The client ID value uniquely identifies your app. However, you no longer need to pass it in the header of all your requests to the API.
The client secret value is a secret that your app and BigCommerce share. You only need to pass the client secret value once, during the app installation sequence. Thereafter, BigCommerce uses it to sign payloads in load, uninstall, and remove user requests, and your app uses it to verify the signature to ensure that the request is coming from BigCommerce.
Delete apps carefully
If you delete the app, there is no way to recover the client ID and client secret.
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 Developer Portal | 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
Legacy API Accounts
As of July 31, 2018, new BigCommerce stores are no longer able to create legacy API Accounts (accounts using HTTP basic auth) within their control panels. Existing legacy API Accounts will continue to work until further notice, but we strongly recommend migrating to OAuth as soon as possible.
Benefits of migrating to OAuth:
It is recommended you migrate from using legacy API credentials to OAuth. Some benefits include the following:
-
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.
-
You can 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 reduce bandwidth usage.
-
Requests are more secure, as all OAuth tokens are scoped to particular endpoints.
How to migrate
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 an access token, by creating an API account within the control panel. 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 tohttps://store-abc123.mybigcommerce.com/api/v2/orders/123
orhttps://my-custom-store-domain.com/api/v2/orders/123
would instead go tohttps://api.bigcommerce.com/stores/{store_hash}/v2/orders/123
.
- Where you previously used the BigCommerce store’s secure hostname, you will instead use the
- With basic auth, you use an authentication HTTP header to authenticate your connection. With OAuth, you’ll want to use the header:
- X-Auth-Token header for your access token. For more information see the article Authentication.
Rate limiting of API requests works differently for OAuth API connections. To become familiar with OAuth limitations, please see the Rate Limits.
OAuth scopes
Scope limits ability to read or write to data. Set the scopes to the minimum level of access 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.
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 | ||
/v3/customers/subscribers/wishlist | ||
store_v2_customers_read_only | View customer information | |
/v2/customers | ||
/v2/customer_groups | ||
/v3/customers/subscribers | ||
/v3/customers/subscribers/wishlist | ||
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/store | ||
/v2//time | ||
store_v2_information_read_only | View general store information and settings | |
/v2/store | ||
/v2/shipping/time | ||
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 |