BigCommerce Authentication: API Credentials & Security (2026)

Authentication overview

BigCommerce offers an API that enables developers to integrate with its e-commerce platform, manage store data, and extend functionality. Access to this API requires proper authentication to ensure that only authorized applications and users can perform operations. The platform supports two primary methods for authentication: API tokens and OAuth 2.0. The choice between these methods depends on the application's nature, its interaction with user data, and the required scope of access.

API Tokens are generally used for server-to-server integrations where an application needs persistent access to a specific BigCommerce store without user intervention. These tokens are static and grant predefined permissions to the API. They are suitable for backend services, data synchronization tools, and custom applications that operate solely within a single store's context.

OAuth 2.0 is the recommended method for applications that require user consent to access store data, such as public or private apps listed in the BigCommerce App Marketplace. OAuth 2.0 facilitates secure delegated access, allowing an application to act on behalf of a user without ever storing the user's login credentials. It involves an exchange process to obtain an access token, which is then used to authorize API requests. This method is aligned with industry-standard practices for secure third-party application access, as detailed in the OAuth 2.0 specification.

Supported authentication methods

BigCommerce provides distinct authentication methods tailored for different integration scenarios. Understanding each method's characteristics is crucial for designing secure and functional applications.

API Tokens (Client ID & Access Token)

API tokens are long-lived credentials generated within the BigCommerce Control Panel. They consist of a Client ID and an Access Token. These tokens are associated with specific API permissions, ranging from read-only access to full read/write capabilities across various store resources (e.g., products, orders, customers).

• When to use: Server-to-server integrations, backend services, private applications built for a single store, headless commerce frontends that access the Storefront API directly.
• Security: High, when tokens are stored securely and permissions are minimized. Requires careful management to prevent unauthorized access.
• Usage: The X-Auth-Token header for Store Management API requests or as part of the URL for Storefront API requests.

OAuth 2.0

BigCommerce implements the OAuth 2.0 framework for applications that require delegated access from store owners or users. This method ensures that applications can access store data without handling sensitive user credentials directly. BigCommerce supports the Authorization Code Grant flow, which is standard for web applications.

• When to use: Public applications, private apps installed by multiple stores, applications requiring user consent, integrations that need to refresh access periodically.
• Security: Very High, as it avoids credential sharing and uses short-lived access tokens with refresh mechanisms.
• Usage: Applications exchange an authorization code for an access token and a refresh token. The access token is then used in the X-Auth-Token header for subsequent API calls. BigCommerce's OAuth API reference details the token exchange process.

OAuth 2.0 Flow Overview for BigCommerce

1. Authorization Request: Your application redirects the store owner to a BigCommerce authorization URL, requesting specific API scopes (permissions).
2. User Consent: The store owner reviews the requested permissions and grants consent.
3. Authorization Code: BigCommerce redirects the user back to your application's specified redirect URL, including an authorization code.
4. Token Exchange: Your application sends a server-side request to BigCommerce's token endpoint, exchanging the authorization code, your application's Client ID, and Client Secret for an access token and a refresh token.
5. API Calls: Your application uses the access token in the X-Auth-Token header to make authenticated API requests.
6. Token Refresh: When the access token expires, your application uses the refresh token to obtain a new access token without requiring user re-authorization, as documented in the BigCommerce OAuth documentation.

The following table summarizes the key authentication methods:

Getting your credentials

To interact with the BigCommerce API, you first need to obtain the appropriate credentials.

For API Tokens (Management API and Storefront API)

1. Log in to your BigCommerce store's Control Panel.
2. Navigate to Account Settings > API Accounts.
3. Click Create API Account > Create V2/V3 API Token.
4. Provide a descriptive name for your API account.
5. Carefully select the necessary API scopes (permissions). Granting only the minimum required permissions is a best practice.
6. Click Save. BigCommerce will display your Client ID, Access Token, and API Path. Make sure to copy these credentials immediately, as the Access Token will only be shown once.

For the Storefront API, you will also generate a Storefront API token with specific channels and customer impersonation capabilities within the same section of the Control Panel. Refer to the BigCommerce API Accounts documentation for detailed steps.

For OAuth 2.0 (Application Development)

If you are developing an application that uses OAuth 2.0, you will need to register your application to obtain a Client ID and Client Secret.

1. Log in to your BigCommerce Partner Portal (or create a partner account if you don't have one).
2. Navigate to Apps > Create an App.
3. Fill in your application's details, including its name, description, and URLs.
4. Crucially, specify the Auth Callback URL(s). This is where BigCommerce will redirect users after they grant consent.
5. Define the required API scopes (permissions) your application will need.
6. After creating the app, BigCommerce will provide you with a Client ID and a Client Secret. These are your application's credentials for the OAuth flow.

These credentials are used in the OAuth token exchange process and should be kept confidential. More information on app registration is available in the BigCommerce app development quickstart guide.

Authenticated request example

Once you have your credentials, you can make authenticated requests to the BigCommerce API. Here's an example using an API token to fetch a list of products from a BigCommerce store using Node.js and the node-fetch library.

const fetch = require('node-fetch');

const storeHash = 'YOUR_STORE_HASH'; // e.g., 'abcdef123'
const accessToken = 'YOUR_ACCESS_TOKEN'; // The X-Auth-Token generated in BigCommerce

async function getProducts() {
  try {
    const response = await fetch(`https://api.bigcommerce.com/stores/${storeHash}/v3/catalog/products`, {
      method: 'GET',
      headers: {
        'X-Auth-Token': accessToken,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Products:', JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Error fetching products:', error);
  }
}

getProducts();

In this example:

• YOUR_STORE_HASH refers to the unique identifier for your BigCommerce store, found in the API path when you create an API account (e.g., https://api.bigcommerce.com/stores/YOUR_STORE_HASH/v3/...).
• YOUR_ACCESS_TOKEN is the API token (X-Auth-Token) obtained from the BigCommerce Control Panel.
• The X-Auth-Token header is essential for authenticating the request.

For OAuth-authenticated requests, the process is similar, but the accessToken would be the one obtained from the OAuth token exchange and dynamically managed (refreshed) by your application.

Security best practices

Securing your BigCommerce API integrations is paramount to protect sensitive store and customer data. Adhering to these best practices helps mitigate common security risks:

• Principle of Least Privilege: Always grant the minimum necessary API permissions (scopes) to your API tokens or OAuth applications. For example, if an application only needs to read product information, do not grant it write access to orders or customers. Regularly review and adjust permissions as needed.
• Secure Credential Storage:
  • API Tokens: Never hardcode API tokens directly into your application's source code. Store them in environment variables, secure configuration files, or a dedicated secret management service (e.g., AWS Secrets Manager, HashiCorp Vault).
  • OAuth Client Secret: The Client Secret for OAuth applications must be kept confidential and never exposed client-side (e.g., in JavaScript running in a browser). It should only be used in server-side code during the token exchange process.
• HTTPS Everywhere: Always use HTTPS for all API communication. BigCommerce APIs enforce HTTPS, ensuring data encryption in transit. This prevents eavesdropping and tampering with requests and responses. This is a fundamental principle of secure web communication, as highlighted by the W3C Web Security FAQs.
• Regular Token Rotation: Periodically rotate your API tokens. If an API token is compromised, rotating it limits the window of exposure. For OAuth, refresh tokens provide a mechanism for renewing access tokens without requiring re-authorization.
• Error Handling and Logging: Implement robust error handling for API responses. Log authentication failures and other security-related events to detect and respond to potential attacks or misconfigurations. Ensure logs do not contain sensitive credentials.
• Input Validation and Output Encoding: Validate all input received from BigCommerce webhooks or API responses before processing it in your application to prevent injection attacks. Similarly, properly encode any data displayed to users to prevent cross-site scripting (XSS) vulnerabilities.
• Rate Limiting Awareness: Be aware of BigCommerce API rate limits (BigCommerce API Rate Limits). Implement exponential backoff and retry logic in your application to handle rate limit errors gracefully, avoiding service disruption and potential IP blocking.
• Webhooks Security: If your application uses BigCommerce webhooks, verify the authenticity of incoming webhook requests using the shared secret provided by BigCommerce. This prevents malicious actors from sending forged requests to your webhook endpoints.
• Stay Updated: Keep your application dependencies, SDKs, and BigCommerce API integration code up to date. BigCommerce regularly updates its API and security guidelines, and staying current ensures you benefit from the latest security enhancements.