What are OAuth Credentials?
BigCommerce uses OAuth authentication for all API and app usage. Currently, there are two workflows to generate tokens, with different use cases.
API Credentials
Credentials for making API requests are created in the control panel and can only be created by the store owner. Tokens created manually through the control panel are referred to in this documentation as API Credentials to distinguish them from tokens created programmatically. API Credentials are used for testing purposes and authenticating scripts, and they are tied solely to the store used to generate them.
Client ID and Client Secret
Credentials for creating apps for sale in the marketplace or private apps are created in Dev Tools, the developer workspace for managing apps. They are referred to as Client ID and Client Secret in this documentation. The Client ID and Client Secret are used by an app to generate an authorization token per store. This allows your app to generate an Oauth token programmatically, eliminating the need to have a merchant manually generate API Credentials to connect an app to their store and allowing your app to generate tokens for multiple stores with a single Client ID and Secret.
Getting API Credentials
You can create and manage API Credentials in the BigCommerce control panel by creating an API account, as described below. Only the store owner can create API accounts; accounts are limited to 50 per store.
To create your API account and its corresponding token, use the following steps:
- Log into the store, using the store owner’s username/password.
- Select Advanced Settings.
- Select API Accounts. This will display the Store API Accounts page.
- Select Create API Account. This will display the Create API Account page shown above.
- In the Name field, summarize the purpose for which you will use these credentials. This name is for internal use only, so assign any name that you will recognize.
- In the OAuth Scopes section, select at least the minimum scopes your app will require.
- Select Save at the page’s lower right-hand corner.
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.
From a security perspective, these credentials are sensitive – please treat them with the same caution that you would treat a private key or root password
To get started making requests, see API Requests.
There is no way to re-display this pop-up after you select Done to dismiss it. Make sure you store your credentials before dismissing the popup, either by copying/pasting the contents of each field or by keeping the downloaded .txt file. Otherwise, you will need to repeat all the above steps to generate new credentials.
Revoking API Credentials
To revoke an OAuth token, use the following steps to delete the associated API account:
- Log into the store, using the store owner’s username/password.
- Select Advanced Settings.
- Select API Accounts. This will display the Store API Accounts page, shown below.
- In the Actions column at right, select the trash-can button next to the account you want to delete.
There is no undo, so be sure before you delete an account. You can also use the checkboxes on the left side to delete multiple accounts at once – but be especially careful when using this option.
Getting Client ID and Client Secret
- The Client ID value uniquely identifies your app. You will 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.
To get a Client ID and Client Secret you will need to log in to Dev Tools. Dev Tools can be accessed by clicking My Apps in the top-right corner of the Developer Portal.
- Click Create an app
- Give your app a name. This will only be visible to you
- 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.
- 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 Dev Tools 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 at any time by clicking View Client ID.
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 Token Type
| Client ID / Client Secret | API Credentials | |
|---|---|---|
| From Dev Tools | X | |
| From Store Control Panel | X | |
| Single Click Apps (Marketplace) | X | |
| Private Apps | X | |
| Hidden Apps | X | |
| Connector Apps | X | |
| Scripts | X | |
| Testing | X | |
| V2 | X | X |
| V3 | X | X |
| Webhooks | X | X |
Migrating from Legacy to OAuth
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.
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.comgateway URL. As an example, requests tohttps://store-abc123.mybigcommerce.com/api/v2/orders/123orhttps://my-custom-store-domain.com/api/v2/orders/123would 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 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 an 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 | ||
| Customers | store_v2_customers | View and modify customer information |
| [/v2/customers]/api-reference/customer-subscribers/customers-api) | ||
| /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_read_only | View order transactions |
| /v3/orders/{id}/transactions | ||
| 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 |