BigCommerce API Authentication: Methods & Setup (2026)

Authentication overview

The BigCommerce API employs standard authentication mechanisms to secure access to store data and functionality. Developers must authenticate their applications or integrations to perform operations such as managing products, orders, customers, and other store resources. The chosen authentication method depends on the application's nature: whether it's a public application installed by multiple merchants or a private integration for a single store.

BigCommerce API supports two primary authentication methods: OAuth 2.0 and API tokens (also referred to as API keys). OAuth 2.0 is the recommended approach for public applications that will be installed by various BigCommerce merchants, as it allows users to grant specific permissions without sharing their credentials directly. API tokens are suitable for private applications or server-to-server integrations where a single store owner grants direct access.

Understanding the distinction and proper implementation of each method is crucial for building secure and functional integrations. BigCommerce maintains detailed documentation on these authentication flows to guide developers through the setup process and ensure compliance with security best practices, as outlined in their comprehensive API documentation portal.

Supported authentication methods

BigCommerce API supports two main authentication methods, each designed for different integration scenarios.

OAuth 2.0

OAuth 2.0 is an authorization framework that enables an application to obtain limited access to a user's protected resources without exposing the user's credentials. For BigCommerce, this means a merchant can grant your application permission to access their store's data (e.g., read products, create orders) without you ever handling their BigCommerce login details. This is the standard for modern API authorization and is particularly suited for public applications listed on the BigCommerce App Marketplace or third-party integrations serving multiple merchants.

BigCommerce utilizes the Authorization Code Grant flow within OAuth 2.0. This flow involves several steps:

1. The application redirects the merchant to BigCommerce's authorization server.
2. The merchant logs in and approves the requested permissions.
3. BigCommerce redirects the merchant back to the application with an authorization code.
4. The application exchanges this authorization code for an access token (and often a refresh token) using its client ID and client secret.
5. The access token is then used to make authenticated requests to the BigCommerce API.

Access tokens typically have an expiration time, after which a refresh token can be used to obtain a new access token without requiring the merchant to re-authorize the application. This ensures continuous access while maintaining security standards, as explained in the BigCommerce API quick start guide on authentication.

API Tokens (API Keys)

API tokens provide a direct method for authenticating requests and are ideal for private applications, custom integrations, or server-side scripts that only need to access data for a single BigCommerce store. Unlike OAuth 2.0, API tokens grant direct access based on the permissions assigned to them. They are long-lived credentials that do not typically expire unless revoked manually.

When using an API token, you include it directly in the HTTP request headers. BigCommerce expects the token in the X-Auth-Token header for most API calls. These tokens are generated within the BigCommerce control panel, where you can also specify granular permissions (e.g., read-only access to products, full access to orders) to restrict what the token can do.

Because API tokens grant direct access and do not expire, they must be treated with the same level of security as a password. Compromised API tokens can lead to unauthorized access to your store's data, highlighting the importance of secure storage and handling practices, as emphasized in BigCommerce's API authentication documentation.

Comparison of Authentication Methods

Getting your credentials

The process for obtaining credentials varies depending on whether you are building an OAuth 2.0 application or a private API token integration.

OAuth 2.0 Credentials (Client ID, Client Secret)

1. Register your App: Navigate to the BigCommerce Developer Portal and register your application. This process will require you to provide an app name, a description, and crucially, a redirect URL (or callback URL) where BigCommerce will send the authorization code after a merchant approves your app.
2. Receive Client ID and Client Secret: Upon successful registration, BigCommerce will provide you with a unique Client ID and Client Secret. These credentials identify your application to BigCommerce's authorization server.
3. Configure Scopes (Permissions): During app registration, you will also define the necessary OAuth scopes, which dictate the specific permissions your app will request from merchants (e.g., store_v2_products_read_only, store_v2_orders).

Securely store your Client Secret. It should never be exposed in client-side code or publicly accessible repositories.

API Token Credentials (API Key)

1. Access BigCommerce Control Panel: Log into your BigCommerce store's control panel.
2. Navigate to API Accounts: Go to Settings > API accounts.
3. Create an API Account: Click Create API Account and select Create V2/V3 API Token.
4. Configure Token Details and Permissions: Provide a name for your API account (e.g., "My Custom Integration") and, most importantly, configure the specific API permissions (scopes) that this token will have. Grant only the minimum necessary permissions to adhere to the principle of least privilege.
5. Generate and Save Token: BigCommerce will generate a unique API key (access token) and a client ID. Immediately save this API key securely, as it will only be displayed once. If lost, you will need to generate a new token and revoke the old one.

For detailed instructions, refer to the BigCommerce guide on API accounts.

Authenticated request example

Here's an example of an authenticated request using an API token to fetch product data. This example uses curl, a common command-line tool for making HTTP requests.

Using an API Token

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products' \
  --header 'X-Auth-Token: {your_api_token}' \
  --header 'Content-Type: application/json'

Replace {store_hash} with your actual store hash (found in the BigCommerce control panel URL or API account details) and {your_api_token} with the API key you generated. The X-Auth-Token header carries your API key, authenticating the request.

Using an OAuth 2.0 Access Token

For OAuth 2.0, the process is similar once you have an access token. The access token is typically included in the X-Auth-Token header, just like an API key. The primary difference is how the token is obtained and managed (via the OAuth flow and refresh tokens).

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products' \
  --header 'X-Auth-Token: {your_oauth_access_token}' \
  --header 'Content-Type: application/json'

In both cases, {store_hash} identifies your specific BigCommerce store, and the X-Auth-Token header holds the credential that grants access.

Security best practices

Adhering to security best practices is paramount when integrating with the BigCommerce API to protect sensitive store data and maintain the integrity of your applications.

• Least Privilege Principle: Always grant the minimum necessary permissions (scopes) to your API tokens or OAuth applications. For example, if an integration only needs to read product information, do not grant it write access to orders. This limits the potential damage if credentials are compromised. The BigCommerce API scopes documentation details available permissions.
• Secure Credential Storage: Never hardcode API keys or OAuth client secrets directly into your application's source code, especially if it's publicly accessible. Instead, use environment variables, secret management services (e.g., AWS Secrets Manager, Google Secret Manager), or secure configuration files. For client-side applications, ensure client secrets are never exposed.
• HTTPS Everywhere: Always use HTTPS for all API communications. BigCommerce API endpoints only accept secure connections, but ensure your application also communicates over HTTPS when exchanging authorization codes, tokens, or sending authenticated requests. This encrypts data in transit, preventing eavesdropping. The OAuth 2.0 framework itself mandates the use of TLS (Transport Layer Security) for all communication.
• Regular Credential Rotation: For API tokens, consider a policy of periodic rotation, especially for critical integrations. While BigCommerce API tokens do not expire, generating new tokens and revoking old ones regularly can mitigate risks associated with long-term exposure.
• Error Handling and Logging: Implement robust error handling for authentication failures. Log authentication attempts and failures (without logging the credentials themselves) to detect potential brute-force attacks or unauthorized access attempts.
• Input Validation: Sanitize and validate all input received from the BigCommerce API and user input before processing. This prevents common vulnerabilities like injection attacks.
• Revoke Compromised Credentials: If an API token or OAuth refresh token is suspected of being compromised, immediately revoke it through the BigCommerce control panel or API.
• Use Official SDKs: Whenever possible, utilize official BigCommerce SDKs for PHP, Node.js, Python, or Ruby. These SDKs are designed to handle authentication flows securely and abstract away much of the complexity, reducing the chance of implementation errors. The BigCommerce SDK documentation provides more information.
• Monitor API Usage: Regularly monitor your API usage logs for unusual activity or excessive requests, which could indicate unauthorized access or abuse of your credentials.